Skip to main content

Web2PrintCanvasAttributeController

You get this controller when useAttribute(...) resolves a Web2Print canvas attribute. It exposes a full canvas editing surface: add/update/remove text, image, and shape elements, reorder layers, and query the fonts and settings that back the editor. Element mutations go through a command manager, so most edits support undo/redo.

import { useAttribute } from "@expivi/product-configurator";

const attribute = useAttribute(configurator, attributeCid);

Building a canvas​

Add elements, transform them, and undo the last change. The add* methods return the new element's id.

const id = attribute.addText({
  id: crypto.randomUUID(),
  type: "text",
  text: "Sale",
  fontFamily: attribute.getDefaultFont(),
  fontSize: attribute.getDefaultFontSize(),
  // ...remaining TextCanvasElement fields
} as TextCanvasElement);

attribute.updateElementTransform(id, { left: 100, top: 50, rotation: 15 });
attribute.updateElementStyle(id, { color: "#ff0000", fontWeight: "bold" });

if (attribute.hasUndo) attribute.undo();

API​

The current canvas state (elements, dimensions, background, zoom, viewport) lives at configuredValue.value.

configuredValue​

The first configured canvas value, if present.

createDefaultCanvasState(): CanvasState​

Builds an empty 800×600 white canvas state.

Adding elements​

Each of these runs through the command manager (undoable) and returns the created element's id:

  • addText(textElement: TextCanvasElement): string
  • addImage(imageElement: ImageCanvasElement): string
  • addShape(shapeElement: ShapeCanvasElement): string

addElement(element: CanvasElement): void appends a generic element, assigning it the next layerOrder (not undoable).

Editing elements​

Command-based (undoable) mutations, keyed by element id:

  • updateElementGeneric(elementId, updates: Partial<CanvasElement>) — patch arbitrary fields.
  • updateElementTransform(elementId, transform) — left, top, scaleX, scaleY, rotation (plus width/height for text elements).
  • updateElementText(elementId, text) — set a text element's string.
  • updateElementStyle(elementId, styleUpdates) — text styling: fontWeight, fontStyle, textDecoration, textAlign, textTransform, originalText, color, fontSize, fontFamily, stroke, strokeWidth.
  • updateElementFlip(elementId, flipX?, flipY?) — mirror an element.
  • removeElement(elementId) — delete an element.

Text-only edits throw if the target element is not a text element.

Layers​

  • getLayers(): CanvasElement[] — elements sorted by ascending layerOrder.
  • getLayersSorted(): CanvasElement[] — same list reversed (top layer first).
  • getLayerById(layerId) / getLayerByElementId(elementId) — find one layer.
  • getLayersCount(): number — number of layers.
  • addLayer(elementId, type): CanvasElement — move an existing element to the last layer position and return it.
  • updateLayer(layerId, updates): boolean — patch a layer while preserving its id; false if not found.
  • removeLayer(layerId): boolean — remove the layer (delegates to removeElement); returns true.
  • reorderLayer(fromId, toId): boolean — move a layer (undoable).

Undo / redo​

  • undo() / redo() — step through command history.
  • hasUndo / hasRedo — whether a step is available.

Fonts and text settings​

  • getDefaultFont(): string — default font from settings, else the first available font, else a built-in fallback.
  • getDefaultFontSize() / getMinFontSize() / getMaxFontSize() / getFontSizeStep(): number — multiline font-size bounds from settings.
  • getTextMovement(): "free" | "vertical" | "horizontal" | "disabled"
  • getTextScaling(): ("vertical" | "horizontal")[]
  • getTextMultiline(): boolean
  • getFontFamilyNames(): string[] — unique font names across collections (or fallbacks).
  • getFontCollectionItems(): FontCollectionItem[]
  • getFontItemByName(fontName): FontCollectionItem | undefined
  • getFontUrl(fontName): string | undefined — the font's file_url.

Media directory​

  • getMediaDirectoryId(): string | undefined
  • getMediaDirectoryName(): string | undefined

Low-level integration helpers​

Each command-based method above has an *Internal twin (updateElementGenericInternal, updateElementTransformInternal, updateElementTextInternal, updateElementStyleInternal, updateElementFlipInternal, removeElementInternal, reorderLayerInternal) that mutates state directly without touching command history. getInternalMethods() returns these bound together — they exist for the canvas-editor integration and command implementations, not everyday consumer use.

For all other members, see the Common Attribute API.