Custom UI Buttons

Some sites may wish to expose interactions with the product that is being visualized. For this purpose, custom buttons can be defined that will display on top of the Visual Component in one of the corners and update various product data based on the product’s implementation.

Labels

To get started, we need to create the container for the button information (the <av-native-button> element) and at least one set of data for how the button should be displayed (the <av-native-button-state> element). The <av-native-button-state> element requires that the title attribute be defined, and is used to determine which text to display in the button’s label.

<atlatl-visual ...>
    <av-product ...></av-product>
    <av-native-ui>
        <av-native-button id="native-button">
            <av-native-button-state title="My Title">
            </av-native-button-state>
        </av-native-button>
    </av-native-ui>
</atlatl-visual>

Icons

Next, we need to give the button an icon, and this is primarily defined using one of two formats.

The first option is to provide an <svg> element as a child of the <av-native-button-state>:

<atlatl-visual ...>
    <av-product ...></av-product>
    <av-native-ui>
        <av-native-button id="native-button">
            <av-native-button-state title="My Title">
                <svg>
                    <path ...></path>
                    <path ...></path>
                </svg>
            </av-native-button-state>
        </av-native-button>
    </av-native-ui>
</atlatl-visual>

Using this first approach, the Visual Component will utilize the icon exactly as specified and not include any additional styling to the image.

The second option is to omit the outer <svg> and only include the standard “inner” elements (such as <path>, <rect>, <circle>, <line>, <polyline>, etc).

<atlatl-visual ...>
    <av-product ...></av-product>
    <av-native-ui>
        <av-native-button id="native-button">
            <av-native-button-state title="My Title">
                <path ...></path>
                <path ...></path>
            </av-native-button-state>
        </av-native-button>
    </av-native-ui>
</atlatl-visual>

Using this second approach, the Visual Component will encapsulate the children in an <svg> element and apply the styling utilized by the Embedded UI, such as when using AR or Snapshot with the native-button attribute as detailed above.

In a scenario where there are multiple <av-native-button-state> elements and we want to utilize the same icon for two or more of the same states, we can forgo defining any children of the state and the state will utilize the icon of the previous state.

<av-native-button id="native-button">
    <av-native-button-state title="My 1st Title">
        <path ...></path>
        <path ...></path>
    </av-native-button-state>
    <av-native-button-state title="My 2nd Title"></av-native-button-state>
    <av-native-button-state title="My 3rd Title">
        <line ...></line>
    </av-native-button-state>
</av-native-button>

Note

The first state must always have an icon defined using one of the two above approaches.

Click events

Now that we have the title and icon set up for each button, we now need to have the button do something when it is clicked. There are three options — that can be combined together if needed based on the implementation — for reacting to the button being clicked.

Firstly, we can have the button set one or more properties on the product to a specified value using the data-av-property attribute to define the property to update (in the scenario where we want to set more than one property, we can provide a comma-separated list of property names) and the data-av-value attribute to define the value to use. Additionally, dependency properties can be set using dot notation to reference the children based on the implementation (see the example below).

<atlatl-visual ...>
    <av-product ...></av-product>
    <av-native-ui>
        <av-native-button id="native-button">
            <av-native-button-state id="state-1" title="My 1st Title" data-av-property="myProperty1, myDependency.property2" data-av-value="value">
                <path ...></path>
                <path ...></path>
            </av-native-button-state>
        </av-native-button>
    </av-native-ui>
</atlatl-visual>

The data-av-value attribute supports a few different data types:

• Strings (e.g. data-av-value="myValue")
• Booleans (e.g. data-av-value="true" or data-av-value="false")
• RGB color arrays (e.g. data-av-value="[255, 0, 0]")

Secondly, we can have the button trigger one or more events on the product using the data-av-event attribute to define the event to trigger (in the scenario where we want to trigger more than one event, we can provide a comma-separated list of event names). Additionally, dependency events can be triggered using dot notation to reference the children based on the implementation (see the example below).

<atlatl-visual ...>
    <av-product ...></av-product>
    <av-native-ui>
        <av-native-button id="native-button">
            <av-native-button-state id="state-1" title="My 1st Title" data-av-event="myEvent1, myDependency.event2">
                <path ...></path>
                <path ...></path>
            </av-native-button-state>
        </av-native-button>
    </av-native-ui>
</atlatl-visual>

Lastly, the <av-native-button> element will emit an av-native-button-clicked event whenever the button is clicked that we can listen for in JavaScript and perform any operation we would like. The event has a detail object that contains an eventSource property that is a reference to the <av-native-button-state> element whose label and icon were displayed.

const nativeButton = document.getElementById('native-button')
nativeButton.addEventListener('av-native-button-clicked', (event) => {
    switch (event.detail.eventSource.id) {
        case 'state-1':
            // Do whatever we want
            break
    }
})

Attributes

<av-native-button>

Attribute	Type	Required	Description
native-button-location	string	optional	The corner where the button should display. Supported values are bottom left and bottom right. Defaults to bottom right.

<av-native-button-state>

Attribute	Type	Required	Description
data-av-event	string	optional	The name of the event to trigger on the associated Product.
data-av-property	string	optional*	The name of the property to set on the associated Product.
data-av-value	string	optional*	The value of the property to set on the associated Product.
title	string	required	The text to display in the Embedded UI label.

Important

If used, the data-av-property and data-av-value attributes must be used in conjunction with each other.

Events

<av-native-button>

Event	Description
av-native-button-clicked	Triggered when the custom Embedded UI button is clicked. The event detail is an object with an eventSource property that is the <av-native-button-state> element that was active/displayed at the time the button was clicked.

Methods

<av-native-button>

Method	Description
showNativeButton(show: boolean)	Sets whether to show or hide the Embedded UI button.