Web-component API

• Last updated on March 20, 2025
• •
• 3 minutes to read

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 API of the web component will only be available after it has been loaded and initialized. If you use the Plugin API, you can use it only after calling the function bootstrap(providers, effects).

Methods

init(configuration)

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

Arguments:

• configuration: IHandyEditorInitArgs

Returns: void

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 Partial editor configuration with fields to be updated.

Returns: void

Example:

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

getLineItem()

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

Arguments: none

Returns: ILineItem

Example:

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

getChoices()

Description: Returns a HashMap of the selected option values when the CC options element is enabled in the workflow.

Arguments: none

Returns: Record<string, string | string[]>

Example:

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

setChoices(choices)

Description: Allows you to set the selected option values.

Arguments:

• choices: Record<string, string[]>

Returns: Promise<void>

Example:

editor.setChoices({ 'Color': ['green'] });

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);

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: string[]

Example:

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

Properties

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.

Structure:

{ 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.

Structure: No data

Example:

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

load

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

Structure: No data

Example:

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

error

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

Structure: Error object

Example:

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

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

Structure: No data

Example:

editor.addEventListener("leave", event => {
   location.href = "your_url";
});