Skip to main content

Web-component API

The Web Component API allows you to interact with a web component by calling its methods or receiving and modifying data using its properties, as well as events that the web component sends.

To work with the Web Component API, you need to obtain the appropriate HTML element using any method available in the Document Object Model (DOM). For example, you can use the getElementsByTagName method:

const editor = document.getElementsByTagName("au-handy-editor")[0];

After obtaining the element, you can use the API as follows:

const choicesValues = editor.getChoicesValues();
console.log(choicesValues);

The web component API becomes available only after the editor loads and initializes. If you use the Plugin API, it becomes available only after you call the bootstrap(providers, effects) function.

Methods​

init(configuration, forceReset?)​

Description: Opens a product and initializes the editor with the specified settings and resource paths.

Arguments:

  • configuration: IHandyEditorInitArgs
  • forceReset (optional): boolean — Forces a state reset.

Returns: void

For au-handy-editor-3d, the init and update methods take IHandyEditor3DConfiguration instead of IHandyEditorInitArgs. This interface extends IHandyEditorInitArgs and adds 3D viewer settings — settings.mockup3dViewer.animationControlType, which accepts "none", "slider", or "buttons".

Example:

handyEditor.init({
    integration: {
        tenantId: <yourTenantId>,
        user: {
            id: <userId>,
            token: <userToken>
        },
        storefrontId: <yourStorefrontId>,
        cchubApiGatewayUrl: "https://api.customerscanvashub.com"
    },
    input: {
        productId: <productId>
    },
    resources: {
        assetLibrary: {
            clipartsFolder: "/Image Library/Clipart"
        }
    },
    settings: {
        designViewer: {
            grid: {
                step: 10
            }
        }
    }
});

update(configuration)​

Description: Updates the editor's configuration.

Arguments:

  • configuration: IHandyEditorInitArgs — The configuration fields to update.

Returns: void

Example:

handyEditor.update({
    "localization": { "language": "es" }
});

getLineItem()​

Description: Returns the data needed to proceed to the cart or for other purposes. At the same time, it saves the current design.

Arguments: None

Returns: Promise<ILineItem>

Example:

const lineItem = await editor.getLineItem();
console.log(lineItem);

getChoices()​

Description: Returns a map of the selected option values — option IDs mapped to arrays of value IDs — when the CC options element is enabled in the workflow.

Arguments: None

Returns: Record<number, number[]>

Example:

const choices = editor.getChoices();
console.log(choices);

setChoices(choices)​

Description: Allows you to set the selected option values.

Arguments:

  • choices: Record<number, number[]> — A map of option IDs to arrays of value IDs.

Returns: void

Example:

editor.setChoices({ 1: [2] });

getChoicesValues()​

Description: Returns the selected option values in the format option name : value name. If multiple selections are possible, an array of the value names is returned.

Arguments: None

Returns: Record<string, string[]>

Example:

const choicesValues = editor.getChoicesValues();
console.log(choicesValues);

getOptionInfoByName(name)​

Description: Allows you to get the metadata of an option by its name.

Arguments:

  • name: The name of the option (you can find it in the BackOffice).

Returns: OptionDto — An object describing the option and its values.

Exceptions: Throws an error "option not found" if the option is not found.

Example:

const option = editor.getOptionInfoByName("Color");
console.log(option);

getOptionInfoById(id)​

Description: Allows you to get the metadata of an option by its ID.

Arguments:

  • id: The ID of the option.

Returns: OptionDto — An object describing the option and its values.

Exceptions: Throws an error "option not found" if the option is not found.

Example:

const option = editor.getOptionInfoById(12345);
console.log(option);

getExternalStorageImagesIds()​

Description: Retrieves all image IDs from the external storage that have been used in the current design.

Arguments: None

Returns: string[] — An array of image IDs.

Example:

const ids = editor.getExternalStorageImagesIds();
console.log(ids);

getCurrentContainer()​

Description: Allows you to get the active container (viewer.userEditContainer).

Arguments: None

Returns: SurfaceContainer/LimitedContainer/FullColorContainer/ColorlessContainer

Example:

const container = editor.getCurrentContainer();
console.log(container.type);

getContainerColors(container)​

Description: Allows you to get the colors used in the container.

Arguments:

  • container: SurfaceContainer/LimitedContainer/FullColorContainer/ColorlessContainer

Returns: Promise<Color[]>

Example:

const colors = await editor.getContainerColors(container);
console.log(colors);

getContainerColorsByItems()​

Description: Allows you to get the colors used by design elements (logos, text, QR codes) in the current container.

Arguments: None

Returns: Promise<IItemColors[]> — An array of objects, each containing the item ID, item name, external image ID (if the item is from external storage), and the colors used by the item.

Example:

const colorsByItems = await editor.getContainerColorsByItems();
console.log(colorsByItems);

recolorContainerItems(container, replacement)​

Description: Allows you to replace a color in the container.

Arguments:

  • container: SurfaceContainer/LimitedContainer/FullColorContainer/ColorlessContainer
  • replacement: { from: Color; to: Color }

Returns: Promise<void>

Example:

const container = editor.getCurrentContainer();
const colors = await editor.getContainerColors(container);
await editor.recolorContainerItems(container, { from: colors[0], to: colors[1] });

observeContainerColors(container, cb)​

Description: Allows you to track color changes in the container.

Arguments:

  • container: SurfaceContainer/LimitedContainer/FullColorContainer/ColorlessContainer
  • cb: (colors: Color[]) => void

Returns: () => void — A function to unsubscribe from changes.

Example:

const container = editor.getCurrentContainer();
const unsubscribe = editor.observeContainerColors(container, (colors) => {
  console.log(`Colors of container ${container.id}:`, colors);
  if (colors.length <= 10) {
    unsubscribe();
    console.log(`Observe complete`);
  }
});

openRecolorPanel(color, cb)​

Description: Allows you to open the recoloring panel and track the colors selected by the user.

Arguments:

  • color: Color — The color intended to be changed.
  • cb: (color: Color) => void — Callback function to track changes. It is called when the user selects a color in the recoloring panel.

Returns: () => void — A function to unsubscribe from changes before the panel is closed.

Example:

editor.openRecolorPanel(initialColor, (newColor) => {
  console.log("Selected color:", newColor);
});

getViolationsMessages()​

Description: Allows you to retrieve the editor's warning messages.

Arguments: None

Returns: Promise<string[]>

Example:

const messages = await editor.getViolationsMessages();
console.log(messages);

Properties​

actions​

Description: An object containing methods (actions) that enable programmatic control over the editor's frontend behavior and user interface.

Type: IHandyEditorActions

export interface IHandyEditorActions {
  redo(): void;
  undo(): void;
  finish(): void;
  openApprovalScreen(): void;
  openPanel(type: ActionPanelItemType): void;
  addText(): void;
}

export declare enum ActionPanelItemType {
    text = "text",
    images = "images",
    uploads = "uploads",
    placeholderImage = "placeholderImage",
    externalImageStorage = "externalImageStorage",
    shapes = "shapes",
    templates = "templates",
    options = "options",
    cliparts = "cliparts",
    addQrCodes = "addQrCodes",
    editQrCodes = "editQrCodes",
    designVariants = "designVariants",
    barcode = "barcode",
    custom = "custom",
    recolor = "recolor",
    addItemMenu = "addItemMenu",
    textToImage = "textToImage"
}

Example:

const handyEditor = document.getElementsByTagName("au-handy-editor")[0];
handyEditor.init({...});
handyEditor.actions.undo();

injector​

Description: Allows you to get the provider values.

Type: Injector

Example:

const store = editor.injector.get("STORE_TOKEN");
console.log(store);

Events​

addtocart​

Description: The Handy Editor triggers this event when the customer has finished their customization and added the product to the shopping cart. This event passes the data corresponding to a line item — a single product added to the cart.

Bubbles: Yes

Data:

{ detail: ILineItem }

Example: This is how you can handle this event:

editor.addEventListener("addtocart", event => {
    const cartItem = event.detail;
    console.log(cartItem);
});

change​

Description: This event is triggered after a design change.

Bubbles: Yes

Data: None

Example:

editor.addEventListener("change", event => console.log(event));

optionchange​

Description: This event is triggered after the options are changed in the editor.

Bubbles: Yes

Data: Record<number, number[]>

Example:

editor.addEventListener("optionchange", event => console.log(event.detail));

load​

Description: This event is triggered after the editor is successfully loaded and initialized.

Bubbles: Yes

Data: None

Example:

editor.addEventListener("load", event => console.log(event));

error​

Description: This event is triggered if an error occurs during the editor initialization.

Bubbles: Yes

Data: Error object

Example:

editor.addEventListener("error", event => {
  console.log(event.detail);
});

leave​

Description: This event is triggered when the Back button is clicked in the editor. It allows, for example, returning to the product page.

Bubbles: Yes

Data: None

Example:

editor.addEventListener("leave", event => {
   location.href = "your_url";
});
Last updated on
Was this page helpful?