Use the s_e_cart_inventory_check function to check the stock levels of items in the Cart and take appropriate action before Checkout.

Introduction

To give the customer the best experience and avoid disappointment, you'll want to make them aware of any problems with their Order as soon as possible.

Using the s_e_cart_inventory_check function in the Cart Layout, you can check each row in the current Cart to check that the required quantity is available. Items will remain in the Cart, but a warning message will display.

The function will also check for any Products which have been been disabled, expired or have a selected Attribute which has been disabled. These products will be automatically removed from the Cart and a warning message will be displayed to explain this.

One way to use this function is as immediate feedback when the User loads the Page or adjusts quantity in their Cart. Alternatively, you can run the function on the "Checkout" button press, to run a final check and redirect the User to the Checkout if successful.

Setting up the Cart Layout

In order for the JavaScript to read the up-to-date quantities in the Cart, you'll need to add the following attributes to your Layouts:

Step 1) Add the Cart ID to each item

In the item.liquid file of your Cart Layout, add data-s-e-cart-id="{{this.cart_data.cart_id}}" to the highest level element.

Step 2) Check each item has a quantity input

In the item.liquid file of your Cart Layout, check that the <input> element containing the up to date quantity for this row has the name attribute with the value quantity. e.g. <input name="quantity">

Step 3) Add the function - see next section for options

Add the s_e_cart_inventory_check({}) function - we'll document which Event Listeners and arguments can be used later in this Article.

A common starting point would be to add the function to a button on a click event e.g.

Step 4) Set up an element to display a message when any Cart Items are no longer for sale

If any Products in the Cart are no longer 'enabled' or have been deleted- or if the Product is enabled, but one of the selected Attributes is not, we'll automatically remove these rows from the Cart when the function is run.

Adding the following data-attribute to an element will display a message explaining this when it happens: data-s-e-cart-has-removed-products

Meanwhile you can use the following Liquid to fetch the same message. This is useful if the Page is refreshed after running the function and you wish to keep the message up:

You can clear the message from the session when you believe the User has had a chance to read it and it will no longer be relevant. (In most cases, you'd display this straight after the Liquid version of the message). We'll clear this automatically if the function is run again without removing any products. `

`

We'll explain how you can customize the message itself later in the function options.

How it Works

The function loops over every row in the Cart, and checks the desired Quantity against available Inventory.

Any disabled, expired or deleted Products are removed from the Cart. So are any Products whose selected Attributes have been disabled or deleted.

An item callback function is then run to handle each remaining row of the Cart, carrying out a different behaviour whether that Item is in stock or not.

If every Item in the Cart is in stock, a success callback function will be run, which may for example optionally redirect the User to the Checkout Page.

Handling Products with Different Attributes

As Attributes do not currently have their own Inventory tracking, the function will share out available inventory between all Items in the Cart with the same Product ID.

This means the quantities of each variation of the Product in the Cart will be added up- and if the total is greater than the Global Inventory, all of the rows with this Product ID will return as "out of stock".

Note that where two rows in the Cart list the same Product with different Attributes, the inventory will be shared between them.

s_e_cart_inventory_check Options

The s_e_cart_inventory_check function accepts a single argument containing a settings object. For example:

The table below details the available settings. Leave the setting undefined or remove the setting from the object if you desire to keep default behaviour:

checkout_url

Passing a checkout_url option to the function allows the function to redirect the Page to the Checkout if the inventory check is successful.

If you use a custom success function, this will be available in your parameters. Else, the default success function will use this to redirect the Page.

Default Behaviour Leaving checkout_url undefined means the default Success Function will not redirect to the Checkout.

item_cb

This option allows you to define a custom callback function which runs against each row in the Cart, telling you whether the Item is in stock or not.

The main function will loop over every row of Items in the Cart. For each Item, the default error function will be run.

Available Parameters

***Default Behaviour ***For all items:

• The "max" attribute of the quantity <input> will be adjusted to match the available inventory.

If the item in the row is out of stock:

• The class .s-e-cart-out-of-stock is added to the row element with the data-attribute data-s-e-cart-id

• The following HTML will be added as a sibling element to the quantity

If the Item in the row is in stock:

• The class .s-e-cart-out-of-stock is removed from the row element with the data-attribute data-s-e-cart-id

• Previous error message elements with the class 's-e-cart-inventory-warning' in this row will be removed.

success_cb

The success_cb function runs only if all Cart rows contain a lower quantity than the available inventory, in other words, it runs if all items remaining in the Cart are in stock.

Available Parameters

Default Behaviour

• Any .s-e-cart-out-of-stock classes will be removed from all Cart rows

• Previous error message elements with the class 's-e-cart-inventory-warning' in all rows will be removed.

• If a value for checkout_url is available, the Page will be redirected to the Checkout. Otherwise, it will not refresh the Page.

Using Event Listeners with s_e_cart_inventory_check

On Page Load

This can be useful so that as soon as the User arrives at the Cart they can be updated on whether items are in stock. In this example, we don't want to refresh the Page on success because the User has just arrived on the Cart Page and will need time to review:

***Example ***To be added to the wrapper.liquid file:

On Change

***Example ***To be added to the item.liquid file:

On Click

This is useful if the Customer has clicked the "Checkout" button and you wish to run a final Inventory check first. Here we make use of the checkout_url option and the default Success function:

***Example: ***To be added to the wrapper.liquid file:

How to customise the Shopping Cart Layout

Prerequisites

• You have completed How to Create a Shopping Cart and Guest Checkout

Folder Structure

Cart layouts are stored in the following structure:

marketplace_builder
└───views
    └───partials
        └───layouts
            └───modules
                └───module_14
                    └───product
                        collection.liquid
                        └───custom_cart_layout
                            └───list
                                item.liquid
                                wrapper.liquid

See the full Cart & Checkout folder structure here:

wrapper.liquid

The wrapper.liquid file should contain the code for the main section of code that wraps around the loop of Products in the Cart. It should include the following liquid to insert the loop of Products:

{% assign cart_parsed = context.session.cart | parse_json %}
{% if cart_parsed.size > 0 %}
  {%- include 'modules/siteglide_ecommerce/ecommerce/get/get_products' item_layout: 'item' -%}
{% else %}
  Sorry, your cart is empty.
{% endif %}

Empty the Cart

<button onclick="s_e_cart_empty(true)">Empty Cart</button>

Link to the Checkout Page

Of course, this is just an ordinary link. It will need updating with the slug of your Checkout Page: <a href="/checkout>Proceed to checkout</a>

Reference

The following reference shows how to output useful data about your Cart as a whole:

If you have added Product Attributes to the Products in the Siteglide Admin, you can also access the cart_product_attributes with the following liquid: {{ context.exports.cart_product_attributes }}

Normally though, Attributes will be handled in the next step- the item.liquid file.

item.liquid

The cart layout will iterate in a loop, outputting the item.liquid file for each line in the customer's cart.

Building the Cart's item.liquid file is similar to building an item.liquid layout file for a Product List View. Learn more about the available fields here.

There are some additional points to bear in mind when creating a cart layout's item.liquid file:

Removing an individual Product from the Cart:

The s_e_cart_remove function can be used to remove a line from the cart.

If the cart has several lines containing the same product, but with different attributes, only the targeted line and its attributes will be removed.

In this example, the function is called when a button is clicked and Liquid is used to pass the cart ID into the function:

item.liquid

<button onclick="s_e_cart_remove(true,{{this.cart_data.cart_id}})">
  Remove Item from Cart
</button>

You can optionally pass in a callback function to the third argument to be called after the row has been removed from the cart. In order for this to work, you need to set reload (the first argument) to false.

item.liquid

<button onclick="s_e_cart_remove(false,{{this.cart_data.cart_id}},removeCallback)">
  Remove Item from Cart
</button>

JavaScript

function removeCallback() {
  //Do something
}

Increasing the Quantity of a Product in the Cart:

See the full Article on updating Product quantities here.

item.liquid

<!-- Step 1 -->

<input 
  type="number"
  name="quantity"
  min="1"
  value="{{this.cart.data.quantity}}"
  onchange="s_e_cart_update_quantity(event.target.value,{{this.cart_data.cart_id}},'{{context.authenticity_token}}',false)"
>

wrapper.liquid

<!-- Step 2 -->

<button onclick="s_e_cart_update(false,'{{context.authenticity_token}}')">Update Cart</button>

Note that, after updating this input field, the User will also have to click the "Update Cart" button. Following the link above will lead to a more detailed article.

Outputting the Attributes the User chose for this item:

{% include 'ecommerce/cart_product_attributes' %}

Controlling Inventory

In order to make sure Users do not increase the quantity of items in their Cart, when the Product is out of stock, you could add a "max" attribute to the quantity input:

<input type="number" 
       name="quantity" 
       min="1" 
       max="{{this.inventory.quantity}}" 
       value="{{this.cart_data.quantity}}" 
       onchange="s_e_cart_update_quantity(event.target.value,{{this.cart_data.cart_id}},'{{context.authenticity_token}}')"
/>

In this Article we'll take an in-depth look at the JavaScript needed to update the quantity of items in the Cart Layout.

Introduction

In this Article we'll take an in depth look at the JavaScript needed to update the Cart when the customer makes changes in the Cart itself.

There are two main flows you can implement:

A second choice is between whether you want to reload the Page to get new values or have our JavaScript function live update them for you.

We'll take a look at the key functions involved and the different ways they can be used within your Layout.

The s_e_cart_update_quantity() function

What it does

The function will queue a change to the Cart in your local storage, but will not yet confirm the change- unless you explicitly ask it to.

Where it's commonly used

This function is designed to work as a callback function to Events triggered on the element which controls the quantity of items in the currently viewed Cart e.g. it could be added to this element in the Cart Layout item.liquid file.

Like so:

Arguments and Usage

You must pass the arguments 1-3. Argument 4 is optional.

s_e_cart_update_quantity(value, cart_id, token, update_entire_cart);

1. value - The quantity required of this Item. Usually set to event.target.value if the event was triggered on a target input element.

2. cart_id - Set to {{this.cart_data.cart_id}} to get the ID referring to the current Item in the item.liquid file.

3. token - Set to '{{context.authenticity_token}}'

4. update_entire_cart - Boolean - defaults to false. If you pass true, we'll automatically run the s_e_cart_update() function (see below) as a further callback, confirming the Cart update immediately.

Your choice of which event is watched will affect the User Experience e.g. onkeyup as opposed to onchange.

In conclusion, this function prepares an update to the Cart quantities. In the next section, we'll look at how to apply those changes.

The s_e_cart_update() function

What it does

This function will apply the changes in the Cart quantities that you have already queued using the previously discussed s_e_cart_update_quantity();

Where it's commonly used

You can either use this function directly to confirm Cart changes when the User is ready, or indirectly.

1. If true is passed for the 4th argument of the previously discussed s_e_cart_update_quantity() function, we'll run this function immediately. In this case, you won't need to directly call this function yourself.

2. Normally this function will be used as a callback to an event triggered on a button on your Cart wrapper.liquid file. E.g.

Arguments and Usage

You must pass the arguments 1-2.

s_e_cart_update(reload, token);

1. reload - Boolean - true will refresh the Page after updating; false will not. This can also be overridden by passing in a success_cb function.

2. token - Set to '{{context.authenticity_token}}'

3. check_inventory_after - Boolean - false - will check inventory stock levels without refreshing the page if set to true.

4. success_cb - function - s_e_cart_update_cb_default- optionally pass in a callback function which will be called after the cart has finished updating. Your function will be passed the parameters: reload, check_inventory_after - both are Booleans which can be used to modify behaviour or ignored.

``

Live Updating Cart Values when Reload is set to

false

When passing in a false reload argument, you will need to follow additional steps to update the following:

• The total quantity

• The total price

• The price of the line item that was just updated.

• -optional- the currency symbol

Live Updating Total Quantity

The s_e_cart_update() function will automatically call the s_e_live_cart_update() function for you- but you'll need to wrap your displayed total in a <span> class with the following data-attribute: <span data-s-e-live-cart-quantity>{{items_in_cart}}</span>

Live Updating Total Price

In the wrapper.liquid file, wrap the following element and data-attribute around the Liquid value for the total Cart Price: <span data-s-e-live-cart-total></span>

e.g.

Live Updating Item Price

In the item.liquid file for your Cart Layout, wrap the following element and data-attribute around the Liquid value for the item's price: <span data-s-e-live-cart-item-price="{{this.cart_data.cart_id}}"></span>

e.g.

It is necessary to add this item's Cart ID as the attribute's value, in order to locate the correct record within the Cart. This will continue to use the Liquid value on initial Page load, but will now replace it with the live value when needed.

Live Updating Currency - Optional

Depending on your HTML structure, you may already be displaying the currency symbol. If the JavaScript is overwriting it, you can add the following HTML to have the JavaScript return it when the function runs: <span data-s-e-live-cart-currency></span>

Troubleshooting Enter Button Presses

If you want to allow Users to press the enter button in the quantity input to trigger the event, you may need to modify your wrapper.liquid file so that the Cart is no longer wrapped in a <form> element but a <div> instead. Make sure to adapt your stylesheets if you do this.

We'd recommend against any solution which stops the default submit behaviour on the Cart buttons that should press on focus and enter keypress- as this will negatively impact Accessibility.

Conclusion

If you want Users to be able to instantly update the Cart by changing values in the quantity input, you can run just the s_e_cart_update_quantity(); function with the 4th argument set to true. You may wish to use the onkeyup event for even more instant feedback.

If you want Users to have the option to confirm Cart Quantity updates before they are applied- you'll need to first run s_e_cart_update_quantity() when each input is changed and afterwards run s_e_cart_update() when the User is ready to confirm.