Skip to main content

spektrix-gift-vouchers

Overview​

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

Embedding the component​

Loading code​

The below snippets load javascript that define the functionality of the spektrix-gift-vouchers 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-gift-vouchers" 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-gift-vouchers,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 and custom-domain attributes to match that of your client's.

More examples can be found in the code samples page

<spektrix-gift-vouchers client-name="thetheatre" custom-domain="tickets.thetheatre.org">
    <div>
        <label for="amount">
            Amount
            <input type="text" name="amount" placeholder="amount" data-amount>
        </label>
    </div>
    <div>
        <label for="sendDate">
            Send Date
            <input type="date" name="sendDate" data-send-date>
        </label>
    </div>
    <div>
        <label for="toname">
            To:
            <input type="text" name="toname" data-to-name>
        </label>
    </div>
    <div>
        <label for="fromname">
            from:
            <input type="text" name="fromname" data-from-name>
        </label>
    </div>
    <div>
        <label for="message">
            message:
            <input type="text" name="message" data-message>
        </label>
    </div>
    <div>
        <label for="deliveryType">Delivery type </label>
        <select name="deliveryType" data-delivery-type>
            <option value="CustomerEmail" selected>Customer Email</option>
            <option value="OtherEmail">Other Email</option>
        </select>
    </div>
    <div>
        <label for="deliveryEmail">
            delivery email address:
            <input type="text" name="deliveryEmail" data-delivery-email-address>
        </label>
    </div>

    <button data-submit-gift-voucher>Buy Gift Voucher</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-gift-vouchers>

Handling Dates​

Dates and date pickers are quite hard to work with, especially when using 3rd party solutions. It's worth investing some time upfront considering your client's needs before diving in to this. There is some great advice on this subject in this article.

There are 3 ways you can set a date using this component, and the one you choose will be dependent on how you approach the problem and the way you choose to allow your customers to input the date. If you have already implemented date pickers on your client's site, it would be worth trying the first method (placing the data-send-date attribute on the root element of the date picker) and seeing if that works before trying the second method of manually updating the sendDate property. We'll break out the three methods below:

The data-send-date attribute​

Placing the data-send-date on your input element should allow it to automatically pick up the date from whichever input type you use. When the attribute is placed on the input element, it will listen for the native input event on that element (or the change event on <select> elements in IE11), take the value from the element and attempt to set the sendDate property on the component accordingly. The value must be a string that can be recognised by the Date.parse() method.

If your date picker doesn't fire an input event, it's probably simpler to directly set the sendDate property as outlined below.

Setting the sendDate property​

The sendDate property on the component holds the date the gift voucher will be sent. This is the same property that is set by any input elements holding the data-send-date attribute. This property can only be set to a date object. If you try to set it as anything else it will not work. You can set this property in the below way:

var sendDate = new Date('02-01-2019');
var giftVoucherComponent = document.querySelector('spektrix-gift-vouchers');
    giftVoucherComponent.sendDate = sendDate;

The data-send-date-day, data-send-date-month and data-send-date-year attributes​

If you wish to roll your own separate inputs for day, month and year, we have provided these attributes as an alternative to being able to build up a date. In almost all cases it's likely to be simpler to use one of the previous methods. Each one of these attributes is mapped to a native javascript function which will set the value it's passed from the input element's value property in to the corresponding part of the sendDate property.

data-send-date-day is an interface to the Date.prototype.setDate() which adjusts the day on the sendDate property. It expects an integer representing the day of the month. More info

data-send-date-month is an interface to the Date.prototype.setMonth() which adjusts the month on the sendDate property. It expects an integer between 0 and 11, representing the months January through December. More info

data-send-date-year is an interface to the Date.prototype.setFullYear() which adjusts the year on the sendDate property. It expects an integer specifying the numeric value of the year. More info

We would also recommend looking at our code samples for examples on how to integrate this component with date pickers.

Handling feedback from the component​

When a gift voucher 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 the gift voucher was successfully added to the basket.

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

If the gift voucher was not successfully added to the basket due to an invalid value being sent (eg - an incorrect amount or date) 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 its contents with the error that came back from the server.

If the gift voucher 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 will be shown with the content that is stored within it.

<div data-success-container style="display: none;">Added to basket</div>
<div data-fail-container style="display: none;">Something went wrong, please contact the box office.</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. In the case of "success" this will describe the users current basket, 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 giftVoucherComponent = document.querySelector('spektrix-gift-vouchers');
    giftVoucherComponent.addEventListener('success', function (e) {
        console.log('event', e)
    })

The forward-to configuration attribute​

The functionality of this attribute is described in full below. In short, however, if you add this attribute in with a URL, the user will be forwarded to that page when the component successfully adds a gift voucher 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​

The initial state of a Spektrix Web Component 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 its corresponding property.

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.

forward-to​

Required: no
Type: String
As property: forwardTo

A URL that the customer will be forarded to once posting the gift voucher has been confirmed as successful.

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 its functionality.

data-amount​

Required: yes
Type: number

This is the monetary value of the gift voucher being purchased. Any input element containing this attribute will update the amount 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="number" data-amount></input>

data-display-amount​

Required: no
Type: number

Any element containing this attribute will update the to display the current the monetary value from the input marked with the data-amount attribute.

<span>Amount to gift <span data-display-amount></span></span>

data-to-name​

Required: yes
Type: text

This is the name of the person the gift voucher is for. Any input element containing this attribute will update the toName 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-to-name></input>

data-from-name​

Required: yes
Type: text

This is the name of the person the gift voucher is from. Any input element containing this attribute will update the fromName 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-from-name></input>

data-message​

Required: yes
Type: text

This is the message from the giver to the receiver that will be sent with the gift voucher. Any input element containing this attribute will update the message 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-message></input>

data-delivery-email-address​

Required: no
Type: text

This is the email address the gift voucher will be sent to. Any input element containing this attribute will update the deliveryEmailAddress property to the value it holds whenever a value is entered into it (it listens to the native input event). The value will be taken from the value property on the element, not the attribute. If you do not include this, the component will default to the email addres on the account of the person purchasing the gift voucher which is set later in the sales process.

<input type="text" data-delivery-email-address></input>

data-send-date​

Required: no
Type: date

Any input element containing this attribute will pass the value it holds to the sendDate property which will coerce it into a JS date format. This attribute is best used with <input type="date"> elements and any 3rd party UI plugins that output a full date (think a date picker). The value will be taken from the value property on the element, not the attribute. If you do not want to use the <input type="date"> element (it has very patchy support) or a 3rd party UI plugin, you can set the day, month and year parts of the sendDate property separately using the the data-send-date-day, data-send-date-month and data-send-date-year attributes as per below.

<input type="date" data-send-date></input>

data-send-date-day​

Required: no
Type: number

Any input element containing this attribute will update the day on the sendDate 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="number" data-send-date-day></input>

data-send-date-month​

Required: no
Type: number

Any input element containing this attribute will update the month on the sendDate 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="number" data-send-date-month></input>

data-send-date-year​

Required: no
Type: number

Any input element containing this attribute will update the year on the sendDate 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="number" data-send-date-year></input>

data-submit-gift-voucher​

Required: yes

Any element containing this attribute will trigger an AJAX request posting all the values in the other input elements which will place a gift voucher into the basket. This will be triggered whenever the element is clicked or, when in focus, the user presses the space bar or enter key.

<button data-submit-gift-voucher>Add to Basket</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 the gift voucher to the basket was successful or not.

<div data-success-container style="display: none;">Added to basket</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 the gift voucher to the basket was successful or not.

<div data-fail-container style="display: none;">Something went wrong, please contact the box office.</div>
Last updated on by Theo