Skip to main content

Quick Start - Merchandise

Web Components are a group of modern browser technologies which allow you to define custom HTML elements and their functionality.

At Spektrix, we are providing them to allow you to ship units of application logic to your clients’ pages without having to write any Javascript (if you don't want to).

There are 4 steps* to using a Spektrix Web Component on your client's web site:

  1. Load the polyfills
  2. Load the javascript that defines the Web Component
  3. Add the Web Component to the markup
  4. Write the rest of the markup within it

*Before you do any of this, please ensure that the domain from which you will be serving pages using Web Components is added in Domain Specific Config in your client’s Spektrix system. If you are already using Spektrix APIs or iframes then you probably have this set up already.

Step 1: Load the polyfills​

Web Components are still quite a new technology; this code will help them work in older browsers.

Between the <head> tags of your page, paste in the following code:

<script src="https://webcomponents.spektrix.com/stable/webcomponents-loader.js"></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.

Step 2: Load the javascript that defines the Web Component​

When building a web page, we can use elements like <button> without any setup because they're already baked into the browser. The Spektrix Web Components add new elements into the browser, and to do that we have to load a bit more javascript on every page where they are used.

Copy and paste the below code in to the head, below the polyfill added in step 1:

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

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>

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.

Step 3: Add the Web Component to the markup​

We're nearly there! Now we just need to add the component to the web page and do a little configuration...

Paste the below into the markup between your <body> tags:

<spektrix-merchandise client-name="{client-name}" custom-domain="{custom-domain}" merchandise-item-id="{merchandise-item-id}">
</spektrix-merchandise>

Now it's in the markup, you just have to add in the client name, custom domain (if using), and the ID(s) for the merchandise item(s) you would like to add to the basket.

Client name​

You can find your client name from either Spektrix Support, or if the venue is a new client, from their Spektrix Project Manager. If you are already working with this client and have previously embedded a Spektrix iframe you can find the client name in an iframe URL, eg:

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

In the above URL, "thetheatre" is the client name.

Add the client name into the client-name attribute as follows:

<spektrix-merchandise client-name="thetheatre" custom-domain="{custom-domain}" merchandise-item-id="{merchandise-item-id}">
</spektrix-merchandise>

Custom domain​

If a client is making use of a custom domain, the custom-domain attribute should be populated with this value.

If a client is using custom domains, a URL like the following would open the event list:

https://tickets.thetheatre.org/thetheatre/website/eventlist.aspx

(in this case the custom domain part would be tickets.thetheatre.org)

If a client is not using a custom domain, this attribute can be omitted.

<spektrix-merchandise client-name="thetheatre" custom-domain="tickets.thetheatre.org" merchandise-item-id="{merchandise-item-id}">
</spektrix-merchandise>

Merchandise Item ID​

The merchandiseItemId is the unique identifier for the merchandise item on your client's Spektrix system. Each ID represents only one individual item, so every variation on an item (think small, medium, large t-shirts, for example) will have a unique ID. When an item (or items) is submitted, the item(s) will be added to the basket. You can add multiple IDs to this attribute by separating them with a comma (no spaces), which will add multiple different items to the basket at once.

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

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

Using a tool like Postman, make the call to the above endpoint swapping out {client-name} with your client’s name. Then pick a merchandise item and add its ID to the merchandise-item-id attribute as follows:

<spektrix-merchandise client-name="thetheatre" custom-domain="tickets.thetheatre.org" merchandise-item-id="1213ANPPNPTJDSBPNJDDPKRNVDCBQQRDC">
</spektrix-merchandise>

Step 4: Write the rest of your markup within it​

The component itself contains the functionality to add the merchandise item(s) to the basket; you unlock that functionality by placing your own markup within it.

Try pasting the below in between your <spektrix-merchandise> tags…

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

The functionality of the component is unlocked by custom attributes placed on the elements. To achieve the functionality you see an element performing in the example markup above, add in another element and put the same “data-” attribute on it. Experimenting in this manner is a good way to start understanding how best to work with Spektrix Web Components.

Full details of the attributes and what they do can be found in the full documentation.

Last updated on by Theo