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 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: Promise<boolean>

Example:

const success = await 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 needed 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);

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

Example:

const messages = 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",
    barcode = "barcode",
    changeColor = "changeColor",
    custom = "custom",
    imageColors = "imageColors",
    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";
});