Skip to main content

Design elements

Read the text items, image placeholders, and barcodes on the current design surface, and update them from your host application. Each element list can be narrowed to a specific container. You can also change the container settings of the surface and manipulate the underlying print product model.

Text items​

Text items are the text elements defined in the design data schema. Each item carries the current value, its length limits, and a schema definition with the label, description, prompt, and constraints.

List text items​

Call getCurrentSurfaceTextItems() to get the text items of the active surface.

const textItems = editor.getCurrentSurfaceTextItems();

for (const item of textItems) {
  console.log(item.id, item.name, item.value);
}

Pass { containerId } to narrow the result to a specific container.

const containerItems = editor.getCurrentSurfaceTextItems({
  containerId: "<container_id>",
});

Each TextItem exposes an id, a name, the current value, the lengthLimits, and a schemaDefinition with displayName, description, required, constraints, and prompt. Use schemaDefinition to render the label and placeholder of your input control rather than relying on the internal item name.

Set text content​

Call setTextItemContent() to update a text item by its ID.

const titleItem = textItems.find(item => item.name === "Title");

if (titleItem) {
  await editor.setTextItemContent(titleItem.id, "New Title Text");
}

The second argument is the plain text content to apply. The method resolves when the content has been applied.

Image placeholders​

Image placeholders are the image elements defined in the design data schema. Each placeholder exposes its schema and supports applying an image from the asset library or an uploaded file.

List image placeholders​

Call getCurrentSurfaceImagePlaceholderItems() to get the image placeholders of the active surface.

const placeholders = editor.getCurrentSurfaceImagePlaceholderItems();

for (const placeholder of placeholders) {
  console.log(placeholder.id, placeholder.name);
}

Each PlaceholderItem exposes an id, a name, a subfolder, the contentManipulation, showSelectButton, and allowFolder flags, and a schemaDefinition with the same displayName, description, required, constraints, and prompt shape as text items.

Pass { containerId } to narrow the result to a specific container.

const containerPlaceholders = editor.getCurrentSurfaceImagePlaceholderItems({
  containerId: "<container_id>",
});

List allowed images​

Call getImagePlaceholderAllowedImages() to fetch the images that can be applied to a placeholder.

const mainImage = placeholders.find(p => p.name === "MainImage");

if (mainImage) {
  const images = await editor.getImagePlaceholderAllowedImages(
    mainImage,
    true, // include subfolders
    0,    // skip
    10,   // take
  );

  for (const image of images) {
    console.log(image.id, image.name);
  }
}

The last three arguments are optional. Set includeSubfolders to true to include nested subfolders. Use skip and take to page through the results.

Set an image by asset ID​

Call setImagePlaceholderContentByAssetId() to apply a library image to a placeholder.

const images = await editor.getImagePlaceholderAllowedImages(mainImage);

if (images.length > 0) {
  await editor.setImagePlaceholderContentByAssetId(mainImage.id, images[0].id);
}

Upload an image​

Call uploadImagePlaceholderContent() to upload a file and apply it to a placeholder.

const fileInput = document.querySelector("input[type='file']") as HTMLInputElement;
const file = fileInput.files?.[0];

if (file) {
  await editor.uploadImagePlaceholderContent(mainImage.id, file);
}

The method accepts the target placeholder ID and a browser File.

Reset placeholder content​

Call resetImagePlaceholderContent() to clear the image content of a placeholder.

const mainImage = placeholders.find(p => p.name === "MainImage");

if (mainImage) {
  await editor.resetImagePlaceholderContent(mainImage.id);
}

Barcodes and QR codes​

Barcode items are the barcode and QR code elements defined in the design data schema. Each item describes its subtype, its format, and a data payload whose shape depends on the subtype.

List barcode items​

Call getCurrentSurfaceBarcodeItems() to get the barcode and QR code items of the active surface.

const barcodeItems = editor.getCurrentSurfaceBarcodeItems();

for (const item of barcodeItems) {
  console.log(item.id, item.name, item.subType, item.format);
}

Each IBarcodeItem exposes an id, a name, a subType, a format, and a data payload. The subType is one of the BarcodeSubType values, and format is one of the BarcodeFormat values.

Pass { containerId } to narrow the result to a specific container.

const containerItems = editor.getCurrentSurfaceBarcodeItems({
  containerId: "<container_id>",
});

Set a URL QR code​

Call setBarcodeItemContent() to update a barcode item by its ID. For a URL QR code, pass BarcodeSubType.URL, BarcodeFormat.QR_CODE, and a data object with a value.

import { BarcodeFormat, BarcodeSubType } from "@aurigma/workflow-elements/headless-editor";

const urlQr = barcodeItems.find(item => item.name === "WebsiteQR");

if (urlQr) {
  editor.setBarcodeItemContent(
    urlQr.id,
    BarcodeSubType.URL,
    BarcodeFormat.QR_CODE,
    { value: "https://example.com" },
  );
}

Set a vCard QR code​

For a contact QR code, pass BarcodeSubType.V_CARD with BarcodeFormat.QR_CODE and a vCard data object.

const contactQr = barcodeItems.find(item => item.name === "ContactQR");

if (contactQr) {
  editor.setBarcodeItemContent(
    contactQr.id,
    BarcodeSubType.V_CARD,
    BarcodeFormat.QR_CODE,
    {
      firstName: "Jane",
      lastName: "Doe",
      organization: "Aurigma",
      email: "jane.doe@example.com",
      mobilePhone: "04805718146",
      url: "https://customerscanvashub.com",
    },
  );
}

The vCard shape supports firstName, lastName, organization, position, email, mobilePhone, fax, phone, url, and an addresses list. For other barcode formats, pass a value string and the matching BarcodeFormat, such as BarcodeFormat.EAN_13.

Containers​

A container is a named group of design elements on a surface. The Container model exposes the container name, type, visibility, and visualization settings, as well as the optional color limits (maxColorNumber, paletteUId).

Read the container settings​

Call getCurrentSurfaceContainerSettings() to get the container settings of the current surface.

const container = editor.getCurrentSurfaceContainerSettings();
console.log(container);

Update the container settings​

Call updateCurrentSurfaceContainerSettings() to apply the updated settings to the current surface. Obtain the container from getCurrentSurfaceContainerSettings(), modify it, and pass it back. The method accepts a partial container, so you can pass only the fields you want to change.

For example, this is how you can switch the container to the colorless type and apply a texture visualization to it:

const container = editor.getCurrentSurfaceContainerSettings();

container.type = "Colorless";
container.visible = true;
container.visualization = {
  type: "TextureVisualization",
  opacity: 0,
  enableGlareEffect: false,
  textureName: "texture_2x2",
  textureSource: {
    id: "66def9be3e121d0c93632bbf",
    width: 2480,
    height: 3508,
    pageIndex: 0
  },
  color: null
};

await editor.updateCurrentSurfaceContainerSettings(container);

The type is one of the ContainerType values, and the visualization object combines the color and texture visualization settings, such as the opacity and the glare effect.

For low-level manipulations, the editor exposes the print product model of the current design — the PrintProduct from the @aurigma/design-atoms-model library.

Read the print product model​

Call getCurrentDesignPrintProductModel() to get the model.

const printProduct = editor.getCurrentDesignPrintProductModel();
console.log(printProduct);

Apply changes to the print product model​

Modify the model and pass it to setCurrentDesignPrintProductModel() to apply the changes to the design.

const printProduct = editor.getCurrentDesignPrintProductModel();

printProduct.surfaces.get(0).containers.get(1).items.get(6).text = "<p><span>HI!</span></p>";

editor.setCurrentDesignPrintProductModel(printProduct);

Reference​

Last updated on
Was this page helpful?