Accessing the Library and Data from HTML
This article explains how to use HTML "markup directives" on your web pages to interact with the Store Builder Library.
The easiest way to interact with the Store Builder Library once it has been placed on the website is to add "Markup directives" to HTML tags as described in this article.
The Library will scan HTML contents of the page for markup directives and apply corresponding data and events once directives are recognized.
The markup directives allow your web page to "read" various bits of data from the Library and "set" variables or perform cart operations. Directives are available to access both product-level and order-level data.
All directives have the prefix "data-fsc-", which helps the Library to identified elements expecting interaction. There are few types of markup directives:
- "Data Setters" – directives which instruct the Library to obtain piece of data from the element.
- "Data Getters" – directives which instruct the Library to place a piece of data into the element.
- "Element manipulations" – directives which instruct the Library to change state of the element (for example, hide or show it).
- "Targets" – directives which identify the scope of the data to be set or read.
- "Actions" – directive which lists actions to perform once element is clicked
This example makes it easy to understand how different types of directives work with each other:
<p>Promo code: <input type="text" data-fsc-order-promocode data-fsc-promocode-value /></p> <p>Apply promo code <input type="button" class="btn" data-fsc-action="Promocode" value="Apply Promo Code" /></p> <p>Currently applied Promo code:</label><span data-fsc-order-promocode></span></p>
In this example:
- "data-fsc-order-promocode" instructs Library to place current value of the coupon code into the input field. This is a "Data Getter" – it gets the value of a parameter from the Library and places it into the specified HTML element.
- "data-fsc-promocode-value" instructs the Library to "read" value of the coupon code from the input field once "Apply Coupon Code" action is called. This is a "Data Setter" – the Library will "set" the value of a coupon code parameter when invoked.
- "data-fsc-action="Promocode" instructs the Library to apply coupon code to the session when clicked. This specific action will look for the first occurrence of the "data-fsc-promocode-value" on the page and read value of the coupon code from there.
As you can see, "getters" and "setters" can be used on the same element – in this case the value will be placed and read from the same element.
In general all "data-fsc-*-value" directives tell the Library that data should be "read" from this directive.
Markup directives are "smart" and will act differently when placed to different HTML elements. For example:
- "data-fsc-order-promocode" will set the "value" of the <input> but "innerHTML" value of the <span> element.
- "data-fsc-item-link" will set "href" of the <a> element but "value" of the <input>
Product-Level Markup Directives
Live Interactive Examples
Coupon code example above shows a simple "order" level directives – only one coupon can be applied to the order. However, sometimes you will need to manipulate with specific products:
- Display localized price of a specific product
- Provide links to add or remove product from cart
- Show current state of the product – if it's in the cart or not
To address those cases the Library provides support for product level markup directives:
<span data-fsc-item-path="arkanoid" data-fsc-item-pricetotal data-fsc-smartdisplay></span> <span data-fsc-item-path="arkanoid" data-fsc-item-total></span> <a href="#" data-fsc-item-path-value="arkanoid" data-fsc-action="Add" data-fsc-item-path="arkanoid" data-fsc-item-selection-smartdisplay-inverse>Add to Cart</a> <a href="#" data-fsc-item-path-value="arkanoid" data-fsc-action="Remove" data-fsc-item-path="arkanoid" data-fsc-item-selection-smartdisplay>Remove from Cart</a>
Along with product level directives this example covers advanced capabilities of the Library:
- "data-fsc-item-path"instructs the Library on the scope of the product – "Values for which product should be placed here". In this example, the product is "arkanoid".
- "data-fsc-item-path-value" instructs the Library to use the defined item when actions are to be performed on this element.
A combination of the above allows for advanced manipulation with products:
<a href="#" data-fsc-item-path-value="arkanoid" data-fsc-action="Add" data-fsc-item-path="arkanoid" data-fsc-item-selection-smartdisplay-inverse >Add to Cart</a>
The first pair (data-fsc-item-path-value="arkanoid" data-fsc-action="Add") instructs the Library to add product "arkanoid" to the cart when clicked – when "Add" action is invoked it will look for the "data-fsc-item-path-value" directive in the same element.
The second pair (data-fsc-item-path="arkanoid" data-fsc-item-selection-smartdisplay-inverse) instructs library to only show the whole element if item defined in the "data-fsc-item-path" is not in the cart.
This flexibility allows you, for example, to show and hide elements on the page based on products in the cart.
- "data-fsc-item-pricetotal" instructs the Library to place the value of the original price without discounts here. This is useful for displaying an "original versus current" price comparison.
- Previous element can be used with the special directive "data-fsc-smartdisplay" which instructs the Library to hide the current element if the original price of the item is equal to the current price – which means that no discount was applied to the item defined in the "data-fsc-item-path".
- "data-fsc-item-total" instructs the Library to place the final price of the item (with all discounts applied). This is the price which customer will pay.
- "data-fsc-action" instructs the Library what to do when a user clicks this link.
Here's how this combination might look like on a store without a discount applied:
And, this is how it looks with a discount applied:
Here are all available product level directives:
- data-fsc-item-path – This is required on each product level static html tags – same value as data-fsc-item-path-element
- data-fsc-driver-item-path-value – When used with data-fsc-item-path-value and data-fsc-action="Replace", if data-fsc-item-path-value defines a product configured as an upsell for the driver item, will replace driver item in order
- data-fsc-item-selected – Is this product added to Order? – Boolean
- data-fsc-item-path-element – This is stored product path -string
- data-fsc-item-pid – This is the product ID code – string
- data-fsc-item-quantity – Quantity of product in Order? Will default to 1 if not in order – numeric
- data-fsc-item-quantity-value – Used in conjunction with 'closest' data-fsc-action="Update" will pass to API – numeric
- data-fsc-item-quantityEditable – Value whether this product is editable in order – Boolean
- data-fsc-item-removable – Value whether this product is removable from order – Boolean
- data-fsc-item-price – 'Pretty' price with currency symbol – string
- data-fsc-item-priceValue – Price value – numeric
- data-fsc-item-priceWithoutTax - 'Pretty' pre-tax price with currency symbol - string
- data-fsc-item-priceValueWithoutTax - Pre-tax price value - numeric
- data-fsc-item-priceTotal – (quantity x priceValue) 'Pretty' price with currency symbol – no discounts included – string
- data-fsc-item-priceTotalValue – (quantity x priceValue) no discounts included – numeric
- data-fsc-item-unitPrice – (priceValue – unitDiscountValue) 'Pretty' price – string
- data-fsc-item-unitPriceValue – (priceValue – unitDiscountValue) – numeric
- data-fsc-item-unitPrice – Discount value for each unit 'Pretty' price - string
- data-fsc-item-unitDiscountValue – Discount value for each unit – numeric
- data-fsc-item-discountPercentValue – Discount percentage for each unit – numeric
- data-fsc-item-discountTotal – Discount 'Pretty' price total for product – string
- data-fsc-item-discountTotalValue – Discount price total for product – numeric
- data-fsc-item-total – 'Pretty' price total after any discounts – string
- data-fsc-item-totalValue – Price total after any discounts – numeric
- data-fsc-item-image – contains the full path to product image – string
- data-fsc-item-display – Product display name – string
- data-fsc-item-description-summary – Returns product short description – html <p>...</p>
- data-fsc-item-description-full – Returns product long description – html <p>...</p>
- data-fsc-item-description-action – Returns product call to action to populate action buttons – html <p>...</p>
- data-fsc-smartdisplay - Should only be used on the data-fsc-item-price or data-fsc-item-pricetotal and will show or hide the element depending on the price difference. You can also assign a DOM element to be operated on - data-fsc-smartdisplay='someDomElement'
- data-fsc-autoapply – When applied to quantity <input> element, no submit button click event needed for xhr update, will xhr update on keyup and change events.
In the "Markup Basics" section of this article, we analyzed an example of a "order-level" directive. Order-level directives do not require a specific product path to be defined on the element because they apply to the order in general. Here are all available order-level directives:
- data-fsc-order-currency – Order 3 digit currency code (ex USD) – string
- data-fsc-order-tax – 'Pretty' order tax – string
- data-fsc-order-taxRate - Percentage rate of the VAT / GST / sales tax for the order - string
- data-fsc-order-taxValue – Order tax – numeric
- data-fsc-order-totalWithTax – 'Pretty' (order-totalValue + order-taxValue) – string
- data-fsc-order-totalWithTaxValue – (order-totalValue + order-taxValue) – numeric
- data-fsc-order-discountTotal – 'Pretty' order total discounts – string
- data-fsc-order-discountTotalValue – Order total discounts – numeric
- data-fsc-order-totalValue – Order grand total - numeric
- data-fsc-order-total – 'Pretty' order grand total - string
- data-fsc-order-taxType – Type of tax applied to the order - "US", "VAT", "GST" or "JP"
- data-fsc-order-country – Order 2 digit country code (ex US) - string
- data-fsc-order-language – Order 2 digit language code (ex en) - string
- data-fsc-order-promocode – Order coupon/promo code - string
- data-fsc-promocode-value – Used in conjunction with data-fsc-action="Promocode" will pass to API
- data-fsc-order-paypal-available - Used in conjunction with data-fsc-smartdisplay will let you show or hide a button that calls data-fsc-action-PaypalCheckout based on whether or not PayPal is currently available for the session.
The data-fsc-action directive allows you to assign various cart-related actions to buttons and links. Actions can also be order or product level:
- Add – product-level action which instructs the Library to add to cart the product defined in data-fsc-item-path-value
- Replace - product-level action for use with upsells only that instructs the Library to remove the product defined in data-fsc-driver-item-path-value from the cart, and replace it with the product defined in data-fsc-item-path-value IF the latter is configured as an upsell for the former (the driver item)
- Remove – same as above, but removes a product from the cart
- Update – same as above, but updates quantity. Once this action is called, the Library will read the product path from data-fsc-item-path-value and find the 'closest' data-fsc-item-quantity-value from which to read the new quantity.
- Promocode – will apply the coupon code found with data-fsc-promocode-value
- TaxId - the value passed in the data-fsc-order-taxId will be validated in conjunction with the customer's country (detected by geo IP location or set via data-fsc-order-country); if valid, the ID will be applied to the order and no VAT or GST will be collected
- Reset – will reset the current session
- Checkout – will initiate checkout for the current session (optionally looking for the session id value in a data-fsc-session-value attribute placed into the same element)
- PaypalCheckout – will initiate checkout for the current session (optionally looking for the session id value in a data-fsc-session-value attribute placed into the same element) and attempt to skip the Storefront and send the customer directly to PayPal
- ViewCart - when the popup cart is enabled in your Popup Storefront's SETTINGS, launches the Popup Storefront and opens the cart directly instead of the checkout page
Actions can be chained by separating them with commas:
<a href="#" data-fsc-action="Reset,Add,Checkout" data-fsc-item-path-value="arkanoid">Purchase Arkanoid</a>
In the example above once "Purchase Arkanoid" is clicked the cart will be reset, Arkanoid will be added to the cart and visitor will be directed to checkout.