This article applies to Contextual Commerce. (Looking for Classic Commerce documentation?)
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 section.
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:
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:
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:
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:
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:
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
Actions can be chained by separating them with commas:
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.