Web Components
Web Components are a group of modern browser technologies which allow you to define custom HTML elements and their functionality. At Spektrix, we have built a series of these in order to allow you to ship units of business logic to your clients’ pages without having to write any Javascript (if you don't want to).
They will enable end users of websites to interact with Donations, Merchandise, Memberships, and Gift Vouchers as well as with their respective Login & Basket sessions.
These components have been designed these to be as straightforward to implement as possible while also allowing full flexibility of use and content. In other words, they will provide you the ability to use them while also having full control over how they look. Below is a quickstart guide - each unique component's section of documentation also will include full documentation for each component and a (non-extensive) set of operational demo examples with available code.
Implementation
There are three steps to using a Spektrix Web Component on your client's web site:
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.
- Load the javascript
- Add the Web Component to the markup
- Write the rest of the markup within it.
For this example, we will use the <spektrix-basket-summary> component.
Step 1: 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 between the <head> tags of your page:
<script src="https://webcomponents.spektrix.com/stable/spektrix-component-loader.js" async></script>
Step 2: Add the Web Component to the markup
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-basket-summary client-name="{client-name}" custom-domain="{custom-domain}">
</spektrix-basket-summary>
Now it's in the markup, you just have to add in the client name and custom domain.
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-basket-summary client-name="thetheatre" custom-domain="{custom-domain}">
</spektrix-basket-summary>
Custom domain
Almost all Spektrix integrated websites will be making use of a custom domain to serve client-side API content or iframes. 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 iframe:
https://tickets.thetheatre.org/thetheatre/website/eventlist.aspx
In this case the custom domain part would be tickets.thetheatre.org
<spektrix-basket-summary client-name="thetheatre" custom-domain="tickets.thetheatre.org">
</spektrix-basket-summary>
Step 3: Write the rest of your markup within it
The component itself contains the functionality to determine what is in the user's basket. You unlock that functionality by placing your own markup within it.
Try pasting the below in between your <spektrix-basket-summary> tags…
<span data-basket-item-count></span> item(s)
<br />
Discount:
<span data-basket-summary-currency></span>
<span data-basket-summary-discount-total></span>
<br />
Total:
<span data-basket-summary-currency></span>
<span data-basket-summary-basket-total></span>
The functionality of the component is unlocked by custom attributes placed on the component itself as well as the child 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 for the <basket-summary> component can be found in the full documentation.
Interaction layers
Spektrix Web Components have three distinct layers for interacting with their state. Understanding these layers is important for getting the most out of the components, particularly if you are writing custom JavaScript.
1. Configuration attributes (HTML)
These are placed on the component tag itself and set the initial state of the component. They map to properties on the component and are the standard way to configure a component when it first loads.
<spektrix-donate client-name="thetheatre" custom-domain="tickets.thetheatre.org" fund-id="123ABC" donation-amount="10">
</spektrix-donate>
Each component's full documentation page lists all available configuration attributes.
2. Internal markup data-* attributes (end-user interaction)
These are placed on child elements inside the component, such as buttons, inputs, and display elements. They are designed for end-user interaction. For the four components which accept user input (<spektrix-donate>, <spektrix-memberships>, <spektrix-merchandise>, and <spektrix-gift-vouchers>) the component automatically listens for native DOM events (like click and input) on these elements and updates its internal state accordingly.
<spektrix-donate client-name="thetheatre" fund-id="123ABC">
<button data-donate-amount="10">£10</button>
<input type="text" data-custom-donation-input>
<button data-submit-donation>Donate</button>
</spektrix-donate>
Input elements with interactive data-* attributes can have default values set directly in the HTML. When the component initialises, it reads the current values from all internal input elements and syncs them to its properties. This means you can set initial state either via configuration attributes (layer 1) or via default values on input elements (layer 2), whichever is more natural for your use case.
<spektrix-donate client-name="thetheatre" fund-id="123ABC">
<input type="text" data-custom-donation-input value="25">
<button data-submit-donation>Donate</button>
</spektrix-donate>
In this example, donationAmount will be initialised to 25 because the component reads the input's value when it connects to the DOM.
3. Properties via JavaScript (programmatic control)
Each configuration attribute has a corresponding JavaScript property on the component element. If you need to control a component's state from your own scripts, set these properties directly rather than programmatically setting values on internal input elements.
const donateComponent = document.querySelector('spektrix-donate');
donateComponent.donationAmount = 25;
donateComponent.fundId = '456DEF';
If you are writing JavaScript to control a component, always use the component's properties (layer 3). Do not programmatically set values on internal data-* input elements (layer 2) — those are designed for end-user interaction via native DOM events, and setting their values programmatically will not fire those events, so the component's state will not update.
The sync() method
Components that accept internal input elements expose a public sync() method. Calling sync() reads the current values from all internal data-* input elements and updates the component's properties to match.
This is a safety net for edge cases where external JavaScript has programmatically set values on internal input elements (layer 2) without firing native DOM events. In most cases you should not need to call sync() — use properties (layer 3) for programmatic control instead.
const donateComponent = document.querySelector('spektrix-donate');
// If for some reason you've set an internal input's value directly:
donateComponent.sync();