Automatic DOM Binding

The Visual Component supports a DOM binding mechanism to bind host site controls (i.e. HTML elements such as buttons, select dropdowns, and radio/checkbox inputs) to properties and events on the Visual Component, such as updating the product with new colors, new materials, and more.

Initialization

To initialize the DOM binding, add the av-binding tag inside your av-product tag, and point its src attribute to the DOM binding JavaScript file:

<atlatl-visual client-id="a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5">
    <av-product namespace="my_namespace" name="my_product_name">
        // highlight-next-line
        <av-binding src="https://builds.dopple.io/atlatl-visual-component/releases/current/bindings/dom/index.js"></av-binding>
    </av-product>
</atlatl-visual>

Then, add the data-av-property and data-av-value attributes to any <button>, <select>/<option>, <input type="checkbox"> or <input type="radio"> elements that are outside of the <atlatl-visual> tag to bind them to Dopple Visual so that the product will be updated when those elements are clicked/changed.

The available values for these attributes will be listed out for you in the configurability matrix provided to you by Dopple.

Tip

The product’s default configuration values will be overridden by any values detected by the DOM binding once initialized on the page.

This can be handy for customizing the default appearance of the product on the frontend, instead of needing to modify the product’s manifest on the backend.

Button binding

To bind a <button> element on your page to control your 3D product, add the data-av-property and data-av-value attributes to the <button> tag itself:

<button data-av-property="product_color" data-av-value="red">
    Red
</button>

Radio button binding

To bind an <input type="radio"> element on your page to control your 3D product, add the data-av-property attribute to any parent <div> element of the <input>, and the data-av-value attribute to any number of <input type="radio"> tags within that <div>:

<div data-av-property="product_color">
    <label>
        <input type="radio" name="product_color" data-av-value="red" checked="" />
        Red
    </label>
    <label>
        <input type="radio" name="product_color" data-av-value="blue" />
        Blue
    </label>
</div>

Note in the example above that the containing <div> does not need to be a direct parent of the bound <input> elements — any grandparent level up the DOM tree will do.

Caution

The name attribute’s value must match a data-av-property attribute value from a parent <div> element in order to trigger updates on the product.

Caution

When using the DOM binding attributes on radio buttons, you must add the checked attribute to one radio button per group in order to set the default value for that property to be loaded with.

If a radio button group has no option checked by default, the product will fail to display and the console will show a InvalidOperationError: Failed to validate property with value 'undefined' error message.

Checkbox binding

To bind an <input type="checkbox"> element on your page to control your 3D product, add the data-av-property attribute to the <input> tag itself:

<input type="checkbox" data-av-property="toggle_part_of_my_product" checked="" />

Caution

The automatic DOM binding for checkbox inputs does not take in a data-av-value attribute. Instead, the bound property will be set to true or false depending on the checkbox’s state.

Be sure to configure this property on your product to accept a boolean value instead of an explicit name, such as my-property-on or my-property-off.

Select menu binding

To bind a <select> menu element on your page to control your 3D product, add the data-av-property attribute to the <select> tag itself, and the data-av-value attribute to its children <option> tags:

<select data-av-property="product_color">
    <option data-av-value="red">Red</option>
    <option data-av-value="blue">Blue</option>
    <option data-av-value="yellow">Yellow</option>
    <option data-av-value="green">Green</option>
</select>

Full code example

index.html

<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>My Page</title>
        <!-- Link to the Visual Component's scripts -->
        <script src="https://builds.dopple.io/atlatl-visual-component/releases/current/index.js" defer></script>
    </head>
    <body>
        <!-- The Visual Component -->
        <atlatl-visual client-id="a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5">
            <av-product namespace="my_namespace" name="my_product_name">
                <av-binding src="https://builds.dopple.io/atlatl-visual-component/releases/current/bindings/dom/index.js"></av-binding>
            </av-product>
        </atlatl-visual>
        <!-- Bound UI elements outside the Visual Component to control the product's configuration -->
        <div>
            <!-- Button binding -->
            <button data-av-property="product_color" data-av-value="[255, 0, 0]">
                Red
            </button>
            <!-- Radio button bindings -->
            <div data-av-property="product_material">
                <label>
                    <input type="radio" name="product_material" data-av-value="material_metallic" checked="">
                    Metallic
                </label>
                <label>
                    <input type="radio" name="product_material" data-av-value="material_matte">
                    Matte
                </label>
            </div>
            <!-- Checkbox binding -->
            <input type="checkbox" data-av-property="toggle_part_of_my_product" checked="" />
            <!-- Select dropdown menu binding -->
            <select data-av-property="product_size">
                <option data-av-value="size_large">Large</option>
                <option data-av-value="size_medium">Medium</option>
                <option data-av-value="size_small">Small</option>
            </select>
        </div>
    </body>
</html>