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 scans HTML contents of the page for markup directives. It applies 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 that instruct the Library to obtain a piece of data from the element.
- "Data Getters" – directives that instruct the Library to place a piece of data into the element.
- "Element manipulations" – directives that instruct the Library to change the state of the element (for example, hide or show it).
- "Targets" – directives that 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 the current value of the coupon code into the input field. This directive 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" the value of the coupon code from the input field when the "Apply Coupon Code" action is called. This directive 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 looks for the first occurrence of the "data-fsc-promocode-value" on the page, and reads the coupon code from there.
As you can see, "getters" and "setters" can be used on the same element – in this case, the value is 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 the "href" of the <a> element but "value" of the <input>
Product-Level Markup Directives
Live Interactive Examples
The 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="example1" data-fsc-item-pricetotal data-fsc-smartdisplay></span>
<span data-fsc-item-path="example1" data-fsc-item-total></span>
<a href="#" data-fsc-item-path-value="example1" data-fsc-action="Add"
data-fsc-item-path="example1" data-fsc-item-selection-smartdisplay-inverse>Add to Cart</a>
<a href="#" data-fsc-item-path-value="example1" data-fsc-action="Remove"
data-fsc-item-path="example1" 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 "example1".
- "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:
>Add to Cart</a>
The first pair (data-fsc-item-path-value="example1" data-fsc-action="Add") instructs the Library to add product "example1" 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="example1" 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 directive is useful for displaying an "original versus current" price comparison.
- You can use the previous element with the special directive "data-fsc-smartdisplay".This approach instructs the Library to hide the current element if the original price of the item is equal to the current price, meaning that no discount has been 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 that the 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 use the product's default quantity 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. When you call this action, the Library reads the product path from data-fsc-item-path-value and finds the 'closest' data-fsc-item-quantity-value from which to read the new quantity.
- Promocode – applies the coupon code found in data-fsc-promocode-value
- TaxId - validates the value passed in data-fsc-order-taxId in conjunction with the customer's country (as detected by geo IP location or set via data-fsc-order-country); if valid, the ID is applied to the order, and no VAT or GST will be collected
- Reset – resets the current session
- Checkout – initiates 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 – initiates 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
You can chain actions together by separating them with commas:
<a href="#" data-fsc-action="Reset,Add,Checkout" data-fsc-item-path-value="example1">Purchase Example 1</a>
In the example above, when a customer clicks the "Purchase Example 1" link, the cart will be reset, Example 1 will be added to the cart, and the customer will be directed to checkout.