Skip to main content

spektrix-donate

Overview​

The spektrix-donate web component is used to offer your clients customers a series of predefined amounts to donate. This document is intended to give you an in-depth view of the functionality and configuration of the spektrix-donate element. For a quick start guide to implementing this component, see here.

Embedding the component​

Loading code​

The below snippets load javascript that define the functionality of the spektrix-donate 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-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..

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-donate,spektrix-merchandise" 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 fund-id to match those of your client's.

More examples can be found in the code samples page

<spektrix-donate client-name="thetheatre" custom-domain="tickets.thetheatre.org" fund-id="2603AMKKPMCKTPCPQBBCPVLVKTNCTTMPQ">
    <span>Amount you are donating: £</span><span data-display-donation-amount></span>
    <button data-donate-amount="10">£10</button>
    <button data-donate-amount="20">£20</button>
    <button data-donate-amount="30">£30</button>
    <button data-donate-amount="0.001">0.001</button>
    <button data-submit-donation>Donate</button>
    <button data-clear-donation>Clear Donation</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-donate>

Handling feedback from the component​

When a donation is submitted 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 donation was successful.

If the donation was successful, it will show the element containing the data-success-container attribute.

If the donation was not successful due to an invalid value being sent (eg - text or a fraction of a penny) or there was another issue with the request, it will show the element containing data-success-container and replace it's contents with the error that came back from the server.

If the donation was not successful because the user is offline or something went wrong handling the request, the element containing data-success-container is shown with the content that is stored within it.

<div data-success-container style="display: none;">Thank you for your donation</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 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-donate');
                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 submitting the donation.

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-donate component is setting the donationAmount property through javascript, such as with a customer controller such as a range input (slider).

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.

fund-id​

Required: Yes
Type: String
As property: fundId

The fundId is the unique identifier for the fund on the client's Spektrix system. You can think of funds as notional "pots" of money where you would put a donation. When a donation is submitted, the amount submitted in that donation will be added to the pot.

You can find the id's for all the funds on a client's system through submitting tgrough The call you would need to make is:

https://system.spektrix.com/{clientName}/api/v3/funds

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 donation has been confirmed as successful.

donation-amount​

Required: no
Type: number
As property: donationAmount

This attribute stores the amount which will be posted as a donation. Setting this on the element as an attribute will effectively give you a default donation amount for the component.

cumulative-mode​

Required: no
Type: boolean
As property: cumulativeMode

When present, every time an element within the component with the "data-donate-amount" attribute is clicked or otherwise activated, the value it holds will be added to the value held in the donationAmount property.

When this attribute is not present, every time an element within the component with the "data-donate-amount" attribute is clicked or otherwise activated, the value it holds will replace the value held in the donationAmount property.

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-donation-amount​

Required: no
Type: boolean

Placing this attribute on an element will update it's textContent to reflect donationAmount. It will only output the number so we would recommend placing the currency symbol before the element you apply this html attribute to.

<span>£</span><span data-display-donation-amount></span>

data-donate-amount​

Required: yes (minimum of one)
Type: number

Any element containing this attribute will update the donationAmount property to the value it holds whenever clicked or, when in focus, the user presses the space bar or enter key.

<button data-donate-amount="10">£10</button>

data-custom-donation-input​

Required: no
Type: boolean

Any input element containing this attribute will update the donationAmount 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-donation-input></input>

data-recognition-name​

Required: no
Type: string

Any input element containing this attribute will update the recognitionName 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-recognition-name></input>

data-is-anonymous​

Required: no
Type: boolean

Any input element containing this attribute will update the recognitionName property to the value it holds whenever a value is entered in to it (it listens to the native input event). If using an checkbox input, the value will be taken from the checked property on the element otherwise the value will be taken from the value property on the element, not the attribute.

<input type="checkbox" data-is-anonymous>

data-tribute-type​

Required: no
Type: string

Any input element containing this attribute will update the tributeTypeId 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.

<select name="tributeType" data-tribute-type>
    <option value="1AHGJDSMMPLMPPGNLJBQVLBRSKVDLQRPP" selected>In honour of</option>
    <option value="2AVDSSBSTSQDRDKBHCNTRTHPNTBGQDTMD">In memory of</option>
</select>

data-tribute-name​

Required: no
Type: string

Any input element containing this attribute will update the tributeName 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-tribute-name></input>

data-submit-donation​

Required: yes
Type: boolean

Any element containing this attribute will trigger an AJAX request posting a donation of the value held in the donationAmount property to the fund held in fundId whenever clicked or, when in focus, the user presses the space bar or enter key.

<button data-submit-donation> Donate</button>

data-clear-donation​

Required: no, but advisable
Type: boolean

Any element containing this attribute will reset the value held in the donationAmount property to 0 whenever clicked or, when in focus, the user presses the space bar or enter key.

<button data-clear-donation > Clear Donation Amount</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 the donation was successful.

<div data-success-container style="display: none;">Thank you for your donation</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 the donation was successful.

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