Skip to main content

spektrix-merchandise

Overview​

The spektrix-merchandise web component is used to offer your clients customers dynamic ways to purchase merchandise online. This document is intended to give you an in-depth view of the functionality and configuration of the spektrix-merchandise element.

Embedding the component​

Loading code​

The below snippets load javascript that define the functionality of the spektrix-merchandise web component. They will need to be added to your page as per your loading strategy.

Before adding the below to your website, ensure you have added the Polyfill loader described in step 1 of the quick start guide.

<script src="https://webcomponents.spektrix.com/stable/spektrix-component-loader.js" data-components="spektrix-merchandise" async></script>

Note: If you are using the Spektrix Basket or Logged in widgets, this code MUST be placed after the code for the widget or you will experience issues in IE11..

If you intend to use multiple components on the same page, you can load them all at once by adding them as a comma separated list in the data-components attribute.

<script src="https://webcomponents.spektrix.com/stable/spektrix-component-loader.js" data-components="spektrix-merchandise,spektrix-donate" async></script>

Basic example​

The below illustrates a basic example of how you could use the element on your page. You will need to change the client-name, custom-domain, and merchandise-item-id to match those of your client's.

More examples can be found in the code samples page

<spektrix-merchandise client-name="thetheatre" custom-domain="tickets.thetheatre.org" merchandise-item-id="1213ANPPNPTJDSBPNJDDPKRNVDCBQQRDC">
    <h2>A merchandise item</h2>
    <div>
        <span>Quantity:
            <span data-display-quantity></span>
        </span>
    </div>
    <div>
        <label for="quantity">
            Custom Quantity
            <input type="text" name="quantity" data-custom-quantity-input>
        </label>
    </div>

    <button data-submit-merchandise>Buy merchandise</button>
    <div data-success-container style="display: none;">Insert success content/markup here</div>
    <div data-fail-container style="display: none;">Insert failure content/markup here</div>
</spektrix-merchandise>

Handling feedback from the component​

When merchandise is added to the basket through this component, you will need to provide feedback to your users or perform other actions based on whether this happened successfully or there was an issue. The following built in functionality is provided to assist you with this.

At this point, it is worth noting that this component does not come with any client side validation but should work well with existing libraries should you wish to use them.

Success/fail containers​

If you place an element in the component that has the attribute data-success-container and one with the data-fail-container and set display: none inline on these elements, the component will display or hide these containers based on whether merchandise was successfully added to the basket.

If the merchandise item was successfully added to the basket, it will show the element containing the data-success-container attribute.

If the merchandise item was not successfully added to the basket due to an invalid value being sent (eg - an incorrect merchandise ID) or there was another issue with the request (eg - the item is out of stock), it will show the element containing data-fail-container and replace it's contents with the error that came back from the server.

If the merchandise item was not successfully added to the basket because the user is offline or something went wrong handling the request, the element containing data-fail-container is shown with the content that is stored within it.

<div data-success-container style="display: none;">Insert success content/markup here</div>
<div data-fail-container style="display: none;">Insert failure content/markup here</div>

These elements are not required for the component to function and their omission does not cause any issues. You could instead build out your own feedback using the success/fail events.

Success/fail events​

As well as success/fail containers, the component itself will emit a custom event of either "success" or "fail" which you can use to provide your own custom feedback to your users. The events also contain the object that is returned from the server which in the case of "success" will describe the users current basket and or, in the case of "fail", it will return the error object provided by the server.

To see this in action, add the below to your page to see the response in your console:

var component = document.querySelector('spektrix-merchandise');
                component.addEventListener('success', function (e) {
                    console.log('event', e)
                })

The forward-to configuration attribute​

The functionality of this attribute is described in full below but in short, add this attribute in with a URL and the user will be forwarded to that page upon the component successfully adding the merchandise to their basket.

We would recommend using this functionality with either a fail container or using the fail event to provide feedback when there are issues.

Configuration Attributes/Properties​

Spektrix web component's initial state is set through attributes placed on the Web Component itself. These values are also accessible as properties on the component. The standard way of working with Web Components is to set the initial state through an attribute on the component then, if you wish to change the state later, changing the value through it's corresponding property.

An example of when you may wish to do with the spektrix-merchandise component is setting the merchandiseItemId property through javascript, with different buttons to represent SKU variations (think Small, Medium, Large on clothes).

client-name​

Required: Yes
Type: String
As property: clientName

The clientName is the unique identifier for the client on the Spektrix system. You'll notice them in our iframe addresses and api calls. For example, in the below iframe:

https://system.spektrix.com/thetheatre/website/eventlist.aspx

In this URL, "thetheatre" would be the clientName.

custom-domain​

Required: No
Type: String
As property: customDomain

The custom domain if the client is using one (e.g. tickets.thetheatre.org). If they are not using a custom domain, this attribute can be omitted.

merchandise-item-id​

Required: Yes
Type: String
As property: merchandiseItemId

The merchandiseItemId is the unique identifier for the merchandise item on the client's Spektrix system. This can hold a single ID or multiple IDs separated by commas (no spaces). When this attribute holds a single ID, the quantity of this item (held in the merchandiseQuantity property) will be posted to the basket. Adding multiple ID's to this attribute allows you to simulate "bundles" or merchandise. When posting to the basket, the component will the amount held in the merchandiseQuantity of each ID.

You can find the ID's for all the merchandise items on a client's system through our APIv3. The call you would need to make is a GET to:

https://system.spektrix.com/{clientName}/api/v3/stock-items

forward-to​

Required: no
Type: String
As property: forwardTo

This attribute unlocks the forward-to functionality of the component. For this component, it will be triggered only once posting the merchandise items has been confirmed as successful.

merchandise-quantity​

Required: no
Type: number
As property: merchandiseQuantity

This attribute stores the quantity of merchandise (represented in merchandise-item-id) which will be posted to the basket. Setting this on the element as an attribute will effectively give you a default quantity for the component.

Attributes to place on internal markup which unlock functionality​

When the component initialises, it places an event listener on itself which listens to all events which fire from child elements of itself. It will examine each event to see if the element which triggered it has one of the below data-* attributes. If it does, it will perform a predefined action described under each data-* element.

The below lists all the attributes you can add to child elements of the component to unlock it's functionality.

data-display-quantity​

Required: no
Type: boolean

Placing this attribute on an element will update it's textContent to reflect merchandiseQuantity.

<span data-display-quantity></span>

data-custom-quantity-input​

Required: no
Type: boolean

Any input element containing this attribute will update the merchandiseQuantity property to the value it holds whenever a value is entered in to it (it listens to the native input event). The value will be taken from the value property on the element, not the attribute.

<input type="text" data-custom-quantity-input></input>

data-submit-merchandise​

Required: yes
Type: boolean

Any element containing this attribute will trigger an AJAX request posting the quantity held in merchandiseQuantity of the merchandise specified in the merchandiseItemId property to the basket whenever clicked or, when in focus, the user presses the space bar or enter key.

<button data-submit-merchandise>Add to Basket</button>

data-increment-quantity​

Required: no
Type: boolean

Any element containing this attribute will increment the value held in the merchandiseQuantity property by 1 whenever clicked or, when in focus, the user presses the space bar or enter key.

<button data-increment-quantity aria-label="Increment merchandise quantity"> + </button>

data-decrement-quantity​

Required: no
Type: boolean

Any element containing this attribute will decrement the value held in the merchandiseQuantity property by 1 whenever clicked or, when in focus, the user presses the space bar or enter key.

<button data-decrement-quantity aria-label="Decrement merchandise quantity"> - </button>

data-success-container​

Required: no, but advisable if not providing feedback for forwardTo or the "success" event Type: boolean

If you place an element in the component that has the attribute data-success-container and one with the data-fail-container and set display none inline on these elements, the component will display or hide these containers based on whether adding merchandise to the basket was successful.

<div data-success-container style="display: none;">Insert success content/markup here</div>

data-fail-container​

Required: no, but advisable if not providing feedback via the "fail" event Type: boolean

If you place an element in the component that has the attribute data-success-container and one with the data-fail-container and set display none inline on these elements, the component will display or hide these containers based on whether adding merchandise to the basket was successful.

<div data-fail-container style="display: none;">Insert failure content/markup here</div>
Last updated on by Theo