Advanced Configurations
Advanced configurations allow you to customise a variety of SparkLayer settings that are used to trigger certain actions on the frontend.
These include actions such as which URL should trigger the My Account Interface (e.g.
/account) to overwriting some of the default text used in the various interfaces. If you're using SparkLayer on a third-party eCommerce platform, many of the below will be automatically enabled by default.
This guide gives an overview of what's possible and our team is happy to help if you have any specific queries.
To enable the advanced configurations, a special code snippet needs to be added to the
<head>...</head> of your main website header beneath the main SparkLayer JavaScript. An example is included below that defines a siteId and the eCommerce platform being used, e.g. ShopifyHTML Example
<head>
...
...
​
<script>
window.sparkOptions = {
siteId: 'your-site-id',
platform: 'shopify'
};
</script>
</head>
SparkLayer supports a range of languages meaning that when users sign in, they see the correct language native to your store. By default, SparkLayer automatically detects the default language of your store but it is possible manually overwrite this if required with the modification of the
language variable.Default language setting
<script>
window.sparkOptions = {
siteId: 'your-site-id',
language: {{ request.locale.iso_code | json }},
...
...
...
};
</script>
Modified language setting
<script>
window.sparkOptions = {
siteId: 'your-site-id',
language: 'en',
...
...
...
};
</script>
Language translations are supported for the following:
Variable | Language |
|---|---|
en | English (default) |
fr | French |
de | German |
es | Spanish |
sv | Swedish |
it | Italian |
pt | Portugese |
el | Greek |
da | Danish |
nl | Dutch |
no | Norwegian |
fi | Finnish |
ro | Romanian |
ar | Arabic |
he | Hebrew |
If you're looking to enable multiple currencies on the same store, it's possible to dynamically generate the required translations but using the below code. Behind the scenes, this will retrieve the language of the customer browsing your store and auto-populate it with the associated language variable (e.g.
en, fr, de, etc)Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
---
language: document.documentElement.lang,
---
};
</script>
If you require a language that isn't on our list, please contact us and we can send details on how to supply translations
When SparkLayer is installed on a website, it replaces the existing My Account and Shopping Cart pages. You can learn more about how this works in our guide here.
SparkLayer has special handling whereby if a customer accesses these pages whilst logged, it will redirect them to the correct SparkLayer interface instead. For example, if they visit
www.yourstore.com/account, it will instead take them to the homepage with the My Account Interface loaded. Key | Details |
accountRedirect | The URL to redirect the user to once they are logged in or if they try and access any account pages. |
cartRedirect | The URL to redirect the user to when the access the /cart URL on your website |
Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
accountRedirect: {
urlRegex: /\/account/g,
goTo: '/#spark-account',
},
cartRedirect: {
urlRegex: /\/cart/g,
goTo: '/#spark-cart',
},
};
</script>
If you're using Shopify, it's even possible to vary the destination link based on a customer tag using the below code sample.
Configuration Code
<script>
...
{% if customer.tags contains 'b2b-tag-1' %}
goTo: "/pages/your-page",
{% else if customer.tags contains 'b2b-tag-2' %}
goTo: "/pages/your-other-page",
{% else %}
goTo: "/index",
{% endif %}
​
...
</script>
If you would like to show the My Account interface or Quick Order Cart on page load, you can do so by adding
#spark-account and #spark-cart to the end of the URL.Related to the above, the SparkLayer Frontend can also be triggered by clicking buttons that may already exist on your website. For example, you may have a prominent link in your website header to the My Account area or the Shopping Cart. SparkLayer has a 'catch all' that simply updates the behaviour any time these buttons are clicked. The available configurations are as follows
Key | Details |
accountButtonSelectors | If the user is logged in, the My Account interface shows. If the user is not logged in, they will be diverted back to your standard login page. |
logoutButtonSelectors | This will log the user out of SparkLayer and, if authLogoutUri is set, it will then forward the user to that location (see below) |
cartButtonSelectors |
Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
accountButtonSelectors: '[href="/account"], [data-spark-link=account]',
logoutButtonSelectors: '[href="/account/logout"], [data-spark-link=logout]',
cartButtonSelectors: '[href="/cart"], [data-spark-link=cart]'
};
</script>
SparkLayer has built-in controls for specific eCommerce platforms that let you overwrite a number of different actions in the storefront experience.
Enabling the eCommerce Platform Configuration can be done with a single line of code
Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
platform:'shopify'
};
</script>
In the example above, Shopify has been enabled as the eCommerce platform. When adding this command, the special SparkLayer configurations are automatically added behind-the scenes. If you need to modify these, you can use the following configurations:
Key | Details |
useSparkLogin | SparkLayer has a built in login modal. By default, this should be set to false to use the existing eCommerce platform login page |
authLogoutUri | The URL that should trigger the user being logged out |
accountRedirect | The URL that the user is redirected to upon successfully signing in |
cartRedirect | The URL the user is redirected to if they access the /cart url |
Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
platform:'shopify',
useSparkLogin: false,
authLogoutUri: '/account/logout',
accountRedirect: {
urlRegex: /\/account((?!\/[login|reset]).*)/g,
goTo: '/',
},
cartRedirect: {
urlRegex: /\/cart/g,
goTo: '/',
},
​
};
</script>
SparkLayer has a built in Login Interface that enables your customers to quickly sign into their account via a modal overlay.
To enable this feature, simply set
useSparkLogin to trueConfiguration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
useSparkLogin: true,
};
</script>
When customers checkout via the SparkLayer Quick Order Interface, they'll be asked to confirm the store's terms and conditions before completing their order.
By default, the terms and conditions link will point to policies/terms-of-service but it's possible to change this via the SparkLayer Core Script by inserting the below snippet.
Configuration Code
termsAndConditionsLink: '/policies/terms-of-service'
It's also possible to adjust the text that shows by including special language overwrites within the same SparkLayer Core Script, as shown below.
Configuration Code
translations: {
en: {
"cart.checkout.terms": {
start: 'I agree to the ',
link: 'terms and conditions',
end: ' ',
},
}
},
You can optionally show live stock levels to your customers when they visit a product detail page.
Stock levels are retrieved dynamically from Shopify (or your backend system if configured) and can even be configured to display different status messages.
To enable this feature, add the following code to the SparkLayer Core Script.
Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
display: {
stock: {
show: true,
max: 50,
last: 5,
low: 15,
},
},
};
</script>
You can adjust the rules of the status messages shown to customers by changing the variables in the configuration code above
Status | Details | Behaviour |
|---|---|---|
max | Stock displays as "XX+ available" | |
last | Let your customers know that the stock level is down to its last items | Message shows as red "Last stock" |
low | Let your customers know that stock level is low | Message shows as orange "Low stock" |
If you're wanting to set a maximum stock level display, you can configure this via the SparkLayer Dashboard. For example, if you set the limit to 50, it will display as 50+ to the customer if the stock level exceeds this. Learn more​
If you're using Tiered Pricing in your price lists, this will display additional information within the Product Purchasing Interface to make it clear to the customer how much they are saving based on how many units they purchase.
By default, the 'Savings' will be calculated based on the single unit price of the particular product (or variant). For example, if the single unit price is $2.00 and if you purchase 5 or more the price reduces to $1.00, the savings will display as -50%
If you'd prefer for the savings to instead be calculated off the RRP (i.e. retail price) of a product, you can enable this within the SparkLayer Core Script.
To enable this, add the following to the core script code added to the
/layout/theme.liquid file within your storefront code.Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
display: {
savingsUseRrp: true,
....
....
},
};
</script>
Please note, you will need to specify RRP (retail prices) for your products for this configuration to work. Learn how to add RRP prices.
You can force customers to complete the 'Additional information' field before proceeding to place their order.
To enable this feature, add the following code to the SparkLayer Core Script.
Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
displayOptions: {
customerReferenceRequired: true,
},
};
</script>
SparkLayer uses 'language strings' to render the text used in the Frontend Interfaces. By default, English is fully supported, but these could be extended to any language if required (see our full list here)
Key | Details |
language | This allows the language to be set (defaults to en) |
translations | This overwrites any languages strings defined in the array, initially key'd by language i.e. en |
showTranslations | If enabled this, shows the language string keys required to change the strings. |
If you're wanting to update specific text elements, it's possible to turn on a special showTranslations view that exposes specific code snippets within the SparkLayer interface. Within the SparkLayer Core Script (in file
/layout/theme.liquid) simply add a new line with showTranslations: trueConfiguration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
...
showTranslations: true,
.....
...
};
</script>
When this setting is enabled, the SparkLayer interface will then render the special language code snippets. In our example below, you can see the language code for the Product Page Interface
We recommend enabling this setting temporarily or onto a non-published theme to ensure it isn't seen by your logged in B2B customers.
To overwrite the text, you then need to add specific code snippets to the SparkLayer Core Script (in file
/layout/theme.liquid). The formatting works by 'cascading' the variables. For example, in the code below, you can see how the pdp.table.price text has been included.Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
...
translations: {
en: {
"pdp.table.price": "Price",
}
}
...
};
</script>
Some important items to note:
- The variable
enmust be replaced with the specific language of your store (see available translations here) - The text overwrites must always end the line with a comma
- If the text overwrite includes a dash (e.g.
product-card), this must be specified with double quotes, i.e."product-card"
If you require a language that isn't on our list, please contact us and we can send details on how to supply translations
For some text content, SparkLayer includes dynamic variables, such as pack sizing or special settings.
If you're looking to make changes to dynamic text within your Shopify store, you'll need to wrap the overwrite text within a special setting
{% raw %}...{% endraw %} to ensure the dynamic variable shows correctly.In our example below, we've shown how this works for the pack sizing text
Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
translations: {
en: {
"global.product-settings": {
{% raw %}
"pack-size": "This product comes in pack sizes of {{packSize}} ",
{% endraw %}
}
},
"pdp.setting-info": {
{% raw %}
"pack-size": "This product comes in pack sizes of {{packSize}} ",
{% endraw %}
}
},
},
},
};
</script>
When a B2B customer signs in and accesses a product that does not have B2B pricing assigned, they'll by default see an 'Unavailable' message (instead of the pricing).
It's possible to update the text that is shown as well as the colour by including the following code to the core script:
Configuration Code
<script>
...
translations: {
en: {
"pdp.messaging.un-sellable": "Unavailable",
"product-card.messaging.un-sellable": "Unavailable",
}
},
...
</script>
You can also update the colour that is shown by adjusting this in the CSS overwrites:
--spark-error-color: #EF0000;
It's possible to prefix the pricing display on a product detail page with custom language such as 'Your price':
To enable, add the following to the SparkLayer Core Script
Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
translations: {
en: {
"pdp.price.from-prefix": "Your Price:"
}
},
};
</script>
If you want to give customers an easy way to show their shipping address for an order, you can optionally display this from their My Account overview by adding the following configuration:
Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
displayOptions: {
orderListShowShippingAddress: true,
},
};
</script>
When a customer reaches the payment step of the SparkLayer Quick Order Interface, they'll see all available payment methods you've set against their customer group. If you'd like to configure the order of the payment methods and which payment method shows by default, you can do this by updating the SparkLayer Core Script with a special setting detailed below.
Configuration Code
<script>
window.sparkOptions = {
siteId: 'your-site-id',
// Update the displayOptions as shown below
displayOptions: {
// Start
paymentOptionsOrder: [
"paymentOnAccount",
"paymentByInvoice",
"upfrontPayment",
"quote",
],
// End
},
};
</script>
In the example detailed above, Payment on account is listed first, making it the default shown to customers. You can amend the ordering using the naming conventions below.
Payment method | Setting name |
|---|---|
Payment by invoice | paymentByInvoice |
Payment on Account | paymentOnAccount |
Upfront Payment | upfrontPayment |
Request for quote | quote |
When SparkLayer loads on a product page, it does so by replacing existing components on your store. You can learn about how this works in our guide here.
The advanced configurations can be used to define which elements are hidden or displayed by SparkLayer giving you control over what your wholesale customers do and don't see. Whilst this is useful, it is recommended to use your platform to hide and show elements as this may induce a 'flicker on page load' whilst the SparkLayer JavaScript is loaded.
Configuration Code
<div data-spark="b2c-only">
Only shown for B2C users.
</div>
<div data-spark="b2b-only">
Only shown for B2B users.
</div>
Custom checkout fields allow you to capture additional information from customers during the checkout process. It's a great way to allow customers to add data such as preferred shipping date, Purchase Order numbers, and more! Once enabled, the custom checkout fields will display on the 'Shipping' step of the SparkLayer Quick Order Interface before the customer selects their shipping address.
When a customer completes a custom checkout field, these will be attached to their order data as special 'Notes'. In the context of Shopify, these will display as "Order Notes" which can then be added to packing slips, sent through to a backend system (via the API) and more.
Custom checkout fields work by adding a JavaScript snippet into your storefront theme. For Shopify, this can be done by editing the
/layout/theme.liquid file and adding the code within the SparkLayer Core script as as new element checkoutCustomElements.In our example below, we've included how this would work with an example 'shipping date'. This can also be adapted with a wide range of other field types such as radios, date pickers, text fields (see below for the full list)
Example with a shipping date
Example with multiple custom fields
<script>
window.sparkOptions = {
​
// Existing core script code above this
​
checkoutCustomElements: [
{
name: "delivery-date",
translations: {
en: {
title: "Delivery Date",
detail: "Delivery unavailable on weekends."
}
},
attributes: {
required: true,
type: "date"
}
},
],
// Existing core script code below this
}
</script>
<script>
window.sparkOptions = {
​
// Existing core script code above this
​
checkoutCustomElements: [
{
translations: {
en: {
title: "Text field",
detail: "Explains what the field is for. Must be 2 letters followed by 2-4 digits"
}
},
name: "text-field",
attributes: {
required: true,
type: "text",
placeholder: "Placeholder shows inside the empty input",
minlength: 4,
maxlength: 6,
pattern: "[a-zA-Z]{2}[0-9]{2,4}"
}
},
{
translations: {
en: {
title: "Number field",
}
},
name: "number-field",
attributes: {
type: "number",
step: 5,
min: 15,
max: 25,
}
},
{
translations: {
en: {
title: "Date field",
}
},
name: "date-field",
attributes: {
type: "date"
}
},
{
translations: {
en: {
title: "Time field",
}
},
name: "time-field",
attributes: {
type: "time"
}
},
{
translations: {
en: {
title: "Week field",
}
},
name: "week-field",
attributes: {
type: "week"
}
},
{
translations: {
en: {
title: "Datetime field",
}
},
name: "datetime-field",
attributes: {
type: "datetime-local"
}
},
{
translations: {
en: {
title: "Checkbox field",
}
},
name: "checkbox-field",
attributes: {
type: "checkbox"
}
},
{
translations: {
en: {
title: "Month field",
}
},
name: "month-field",
attributes: {
type: "month"
}
},
{
translations: {
en: {
title: "Telephone field",
}
},
name: "telephone-field",
attributes: {
type: "tel"
}
},
{
translations: {
en: {
title: "Email field",
}
},
name: "email-field",
attributes: {
type: "email"
}
},
{
translations: {
en: {
title: "URL field",
}
},
name: "url-field",
attributes: {
type: "url"
}
},
]
}
</script>
To get started, we've included some of our most popular customer checkout field types