When to Use?

The Cart and Checkout flow is most likely right for you if your site:

• Will sell a selection of products

  • Physical or Digital

  • Where the user can select one or many to purchase at once

  • Optionally charge for shipping

  • Optionally offer discounts

    • Bulk Discounts

    • Discount Codes

  • Include tax in prices

• Will eventually want to sell the products, but as an extra step will want to send an official quote to the customer for their selection of products.

Customise the way Products look on their automatically generated Detail Pages and add functionality for adding the Product to the Cart.

Prerequisites

• You have created Products in the Admin

Getting Started

This Tutorial will show you how to output information about a Product on its automatically-generated Detail Page.

It will cover how to:

• Find where Product layouts are stored on Code Editor

• Develop a wrapper.liquid file

• Include an item.liquid file

• Add functionality for a User to add the Product to Cart

File Structure

In SITE MANAGER/Code Editor, the folder structure for eCommerce layouts is as below:

• layouts

  • modules

    • module_14

      • product

        • name_of_my_layout

          • list

            • wrapper.liquid

            • item.liquid

          • detail

            • wrapper.liquid

            • item.liquid

      • product_attributes

        • my_attribute_layout.liquid

See more:

Creating a new set of Product Layouts

To create a new set of Product layouts- create your folder at the level of "name_of_my_layout". Inside that, the folders and files should be created as shown above.

Detail Layout Development

As with list views, the detail folder inside your new layout folder should contain a wrapper.liquid and an item.liquid file. Refer to the folder structure at top of the document for reference. You also have the option of creating an attribute layout which can be included inside your item.liquid file to show Product Variations.

wrapper.liquid

wrapper.liquid -- detail view example

<section class="large detail-view ecommerce">
  <div class="container">
    <div class="row">
      {%- include 'modules/siteglide_ecommerce/ecommerce/get/get_products'
          item_layout: 'item' 
      -%}
    </div>
  </div>
</section>

This is the file for the main section code e.g. a section title or padding. You will need to use the following liquid to include your item.liquid file inside the wrapper and give it access to information about the Product:

{%- include 'modules/siteglide_ecommerce/ecommerce/get/get_products'
    item_layout: 'item' 
-%}

item.liquid

item.liquid -- detail view example

<div class="col-lg-6"> <img src="{{this['Image'] | asset_url}}" class="img-fluid"></div>
<div class="col-lg-5 offset-lg-1">
  <div>
    <h2 class="product-title">{{this['name']}}</h2>
    <p class="product-price" data-price-control="{{this.price.price_charge}}" 
       data-currency-control="{{this.price.currency_symbol}}"></p>
    <div class="row">
      <div class="col-md-4">
        <div class="form-group">
          <label>Quantity</label>
          <input type="number" min="1" value="1" class="form-control" data-quantity-control="">
        </div>
      </div>
    </div>
  </div>
  <hr class="mt-4 mb-4">
  
{% if this['Description'] %} <h4>Product Description</h4> {{this['Description']}} {% endif %}
  <hr class="mt-4 mb-4">
  <div class="row product-detail-buttons">
    <div class="col-12 col-md-6">
      {% include 'ecommerce/cart_add' -%}

    </div>
    <div class="col-12 col-md-6">
      <a class="btn btn-primary" href="/cart">View my Cart</a>
    </div>
  </div>
</div>

Unlike the List View, the code in the item.liquid file in the Detail folder will only be displayed once instead of looped. Inside the item.liquid file, you'll have access to the "this" object, which contains the fields you'll need. See reference for available fields or output {{this | json}} in the item.liquid file to see the exact data available to you.

Add to Cart

To create a button to add the current Product to the Cart use the following Liquid code

{%- include 'ecommerce/cart_add', component_layout: 'name_of_my_layout' -%}

See more:

Quantity to Add to Cart

In order to use the "Add to Cart" Button, you'll also need to have an input element where Users can select the quantity they'd like to add. Make sure it has the correct data-attribute.

<label for="quantity">Quantity</label>
<input type="number" min="1" value="1" data-quantity-control id="quantity" />

Similar to WebApp List Layouts, a Product List Layout can allow users to browse Products. It can be filtered and sorted too!

Prerequisites

• You have created Products in the Admin

Getting Started

This Tutorial will show you how to output a list of Products on your site.

It will cover how to:

• Find where Product layouts are stored on Code Editor

• Develop a wrapper.liquid file

• Develop an item.liquid file

Add a List of Products to a Site

{%- include 'ecommerce/products'
    layout: "products"
    category_ids: current_category_id
    type: 'list',
    show_pagination: 'true'
-%}

Parameters:

• layout - choose the layout file for this list.

• category_ids - filter the List by these category ids

• sort_type - the field you wish the sort by

• sort_order - 'asc' or 'desc' - the order you wish to sort by.

• type - Should be list, for a List View layout. This can also be used to display different types of layouts, like a Cart in a different context.

• show_pagination - if pagination should be displayed after the products. Default is 'true'

Folder Structure

If you need to refer to the folder structure for where layout files should go, refer to this:

Creating a new set of Product Layouts

To create a new set of Product layouts- create a new folder bearing the name of your layout, and create within it:

• product

  • name_of_my_layout

    • list

      • wrapper.liquid

      • item.liquid

    • detail

      • wrapper.liquid

      • item.liquid

List Layout Development

A list view for products is made up of two parts.

wrapper.liquid

<div class="row">
  <div class="card-deck"> 
    {%- include 'modules/siteglide_ecommerce/ecommerce/get/get_products'
      item_layout: 'item' 
    -%}
  </div>
</div>

The wrapper contains the code for the main part of the section you are building. For example, the section title or some margin or padding that separates your list from other sections.

In the wrapper.liquid file, it is important to include the liquid file which loops over the Product items:

{%- include 'modules/siteglide_ecommerce/ecommerce/get/get_products'
    item_layout: 'item' 
-%}

The item_layout parameter should be the name of a liquid file in the same folder as the current file. Usually this will be "item", but you could have an alternative Layout.

item.liquid

item.liquid -- list view example

<div class="card">
  <div class="card-img">
    <a href="/{{this.module_slug}}/{{this.slug}}">
      <img src="{{this.Image | asset_url}}" alt="{{this.name}}" class="card-img-top">
    </a>
  </div>
  <div class="card-body">
    <a style="height: 100%" href="/{{this.module_slug}}/{{this.slug}}">
      <h3 class="card-title">{{this['name']}}</h3>
      <p>{{this.price.currency_symbol}}{{this.price.price_charge_formatted}}</p>
    </a>
  </div>
</div>

This file contains the code for each iteration of the loop that displays the Products. You should expect this code to be rendered multiple times; once for each product displayed in the list. (Hint: Try not to run any GraphQL calls inside a loop or item.liquid file, as they would have an impact on performance. It is better to run these inside the wrapper.)

Output all data available in the "this" object: {{this | json}}

Adding to Cart on the List View

Marking Separate Products to support the Advanced Features of Adding to Cart on a Product List View

In order to help the JavaScript understand which Quantity and Attribute Control belongs to which Product, we've added a new requirement to Product List Layouts. Please add the following data-attribute on the highest-level HTML element in your item.liquid file.

In this example, the highest level element in the file is a <div> element which is wrapped around the rest of the content in the file, but yours could be any element. The important thing is that this element is wrapped around any controls in the File.

<div class="card" data-product-group>
  <div class="card-img">
    <a href="/{{this.module_slug}}/{{this.slug}}">
      <img src="{{this.Image | asset_url}}" alt="{{this.name}}" class="card-img-top">
    </a>
  </div>
  <div class="card-body">
    <a style="height: 100%" href="/{{this.module_slug}}/{{this.slug}}">
      <h3 class="card-title">{{this['name']}}</h3>
      <p>{{this.price.currency_symbol}}{{this.price.price_charge_formatted}}   </p>
    </a>
  </div>
</div>

For old sites which do upgrade the eCommerce Module, but do not add this data-attribute, we'll add a console log in dev-tools to act as a reminder, but any functionality which worked previously will continue to work.

Adding to Cart on the List View

As with Detail Layouts, you'll need to include the following Liquid and HTML code within the item.liquid file. It's also now important that these elements lie within the element with the data-product-group Attribute, when you're building a List Layout. See the section above for details.

The "Add to Cart" Button

For more on developing the Add to Cart Button:

The Quantity Control

<input type="number" 
       min="1" 
       max="{{this.inventory.quantity}}" 
       data-quantity-control id="quantity" />  

This is mandatory, but can be hidden and hard-coded to have a value of 1, if you want to simplify the UI:

<input readonly hidden type="number" 
       min="1" 
       max="1" 
       value="1"  
       data-quantity-control id="quantity" />

Attribute Control

Full Example: Example of an item.liquid file in a Product Layout which supports Adding to Cart:

<div class="card" data-product-group>
  <div class="card-img">
    <a href="/{{this['module_slug']}}/{{this['slug']}}" title="">
    <img src="{{this['Image'] | asset_url}}" alt="{{this['name']}}"></a>
  </div>
  <div class="card-body">
    <h2 class="card-title">
      <a href="/{{this['module_slug']}}/{{this['slug']}}" title="">{{this['name']}}</a>
    </h2>
    <p>{{this.price.currency_symbol}}{{this.price.price_charge_formatted}}</p>
  </div>
  
{% include 'ecommerce/cart_add' -%}
  <label for="quantity">Quantity</label>
  <input type="number" min="1" value="1" data-quantity-control id="quantity" />
  {% comment %}-----The following liquid code block loops over all attributes on this Product----{% endcomment %}
  {% for attribute in this.product_attributes %}
    {% if attribute.properties.enabled == true %}
      {% include 'ecommerce/product_attributes' name: attribute.properties.name layout: 'demo_site_attributes' -%} 
    {% endif %}
  {% endfor %}
  <div class="card-footer">
    <p class="tag">
      {% for category in this.category_array %}
        <a class="btn btn-primary" href="{{context.exports.categories.items[category].full_slug}}" title="">
          <i class="fas fa-tag"></i>{{context.exports.categories.items[category].name}}
        </a>
      {% endfor %}
    </p>
  </div>
</div>  

Pre-Requisites

• You have Installed the eCommerce Module

Introduction

The Siteglide Ecommerce Module makes it easy to set up a secure and reliable Shopping Cart and Checkout flow. As usual, you can customise your layouts at every step.

In this tutorial, we will show you how to create the simplest Cart and Checkout flow- the Guest Checkout. Users can buy Products without having to sign in, but their details are stored in the CRM so the Site Owner can send them their Products.

Step 1) Set eCommerce Currency Settings

In eCommerce/Settings, select the desired default currency for your Site:

Step 2) Create Products

In eCommerce / Products, create at least one product with a price:

Step 3) Add a Product List to a Page

Users will need to see your products in order to access their Product Detail Pages, or add to their Carts directly. You can use the following code to add a Product List view with the default layout:

{%- include 'ecommerce/products', layout: 'default', per_page: '20', show_pagination: 'true' -%}

Step 4) Select a Product Detail Layout

To set a Detail Layout, start at eCommerce / Products and click the "View Table" button:

Select the Detail Page Template and Layout:

Step 5) Implement an Add to Cart Button on Your Detail View

...and Optionally on your List View!

Make sure your Product Detail pages have an add to Cart Button in their layout’s item.liquid file.

This liquid include tag will add the "Add to Cart" Button:

`

`

`

`

Step 6) Add a Cart Page

Create a new Page for your Cart and use liquid to include the Cart.

`

`

Use the layout parameter to select the folder which contains the wrapper.liquid and the item.liquid file you would like to use for your layout. For now, you can use the "cart" layout which is included in the eCommerce Module.

Step 7) Create a Form for your Checkout Page

This will store a paying User against the CRM and submit their payment details securely via your chosen Payment Gateway.

You will need to add the following information when creating your form:

• Form Name: e.g. Checkout Form

• Redirect URL - This is the relative URL you want a user to be redirected to after submission of payment details e.g. a confirmation page.

• In the payments tab, toggle "Use as a payment form?" on

• Payment Form Type will appear under the payments tab. Select "Standard Checkout".

Save your changes.

Step 8) Create a new Page for your Checkout Form

Step 9) Add the Checkout form to your Checkout Page

Include the Checkout Layout in your page - use the ID from the CMS / Forms list as the form_id parameter. If you use the Toolbox to add this code, you can lookup your form by name.

`

`

The layout parameter should refer to the folder which contains your form layout file. This file exists here:

layouts/forms/form_2/default.liquid

For now, you can use the "default" layout that is included with the eCommerce module.

If the page is visited while the user has an empty cart, an alternative "empty" layout will show. The default form layout will automatically add an empty layout at the path:

layouts/modules/module_14/checkout/default/empty.liquid

If you create a custom layout, you should also create an empty.liquid file, renaming the default folder in the filepath above with the name of your form layout.

Step 10) Test your eCommerce flow.

Users will be added to the CRM in Admin.

You can see the records of transactions in Admin by navigating to the Orders list or finding the User in the CRM.

Next Steps

You've now completed the simplest version of the Cart and Checkout Flow, however there are plenty of improvements you can still make and lots more to learn.

Orders

After a User has submitted your Checkout form, an order will be automatically generated. You can see a list of orders under ECOMMERCE/Orders in the left-hand menu.

Click on the name of the order for more information.

You can add Secure Zones to this flow in the next article, allowing you to easily show the User their past orders when logged in:

A note on Inventory

As a user buys a Product, the Inventory decreases accordingly.

A User cannot buy a Product if its Inventory is 0, but you can also hide Products that have sold out from the Product List Views.

This Article will look in detail at the JavaScript function which updates the Product price as the customer selects Attributes.

Prerequisites

• Your should be updated to version 1.0.5 to get the latest version of this feature described by this Article. Earlier versions of the Module will have limited support for this feature on Product List views.

• You have on some of your Products and nested inside your Product Layout.

Introduction

On the Product List and Detail Views you can provide customers with an option to select Product Attributes- changing features like "size" or "colour", depending on the Product.

This Article will look in detail at the JavaScript function which achieves this and adjusts the displayed Price of the Product appropriately.

A note on security: the prices we are working with in this topic are cosmetic only. There's no need to worry about malicious users "choosing their own prices" at this stage, as prices will be calculated afresh securely on the server if and when an Order is created.

The s_e_update_price() Function

What it does

This function will update the currently displayed price of a Product to take into account any selected Attributes.

Where it's commonly used

To optionally set the initial prices to be displayed on:

• Product Detail View

• Product List View (support added in eCommerce version 1.0.5)

To update the prices to be displayed on:

• Product Detail View

• Product List View (support added in eCommerce version 1.0.5)

Arguments and Usage

Optional - To Display the Initial Price

To display the initial price of a Products on the Product List, or Detail View, on Page Load, you can run the function within the following Event Listener. No arguments are required.

<script>

   window.addEventListener('load', function() {

      s_e_update_price();

   });

</script>

To Update the Price on Attribute Select

To watch an Attribute for change, add the listener: onchange="s_e_update_price()"to the <select> element in your chosen Attributes Layout:

<label for="{{attribute_name | slugify}}">{{name}}</label>
<select name="attr1" 
        class="form-control" 
        data-attribute-control="{{this_attribute.id}}" 
        onchange="s_e_update_price()">
{% for option in product_attribute_options -%}
<option {% if forloop.first %}selected{% endif %} value="{{option.id}}" 
            data-attribute-price-control="{{option.price_raw}}">
{{option.name}} (+{{this.price.currency_symbol}}{{option.price}})
</option>
{% endfor -%}
</select>

Usage Notes

The JavaScript looks for data in the HTML attributes in order to make its calculations. In the usage notes below we'll detail everything you need to provide for this function to do it's work.

Usage note 1 - Define the element which will dynamically display the product price

The purpose of this function is to dynamically update the displayed Price, but the choice of where this should be within the Layout is up to you.

To mark an element within the item.liquid file as being the element which will receive the dynamic price as its text content when calculated, add the following HTML attributes:

• data-price-control

• data-currency-control

The value of these Attributes should be set using Liquid to the Product's initial price and currency:

<p class="product-price" 
   data-price-control="{{this.price.price_charge}}" 
   data-currency-control="{{this.price.currency_symbol}}">
   {{this.price.currency_symbol}}{{this.price.price_charge_formatted}}</p>

In this example above- we also add the initial Price to the text content of the element using Liquid on Page Load. Instead, you can run the function on Page Load to display the initial price, should you choose.

Usage note 2 - Define the prices of Attribute Options

In order to add the prices of Attributes to the base price- you'll need to define the prices against the <option> element that contains a selectable Attribute Option: data-attribute-price-control="{{option.price.raw}}"

For example:

<option value="{{option.id}}" data-attribute-price-control="{{option.price_raw}}">

      {{option.name}} {{this.price.currency_symbol}}{{option.price}})

</option>

Usage note 3 - When using this Function on the Product List View, add the data-product-group attribute to your item.liquid file

If you're using this function on the Product List View, you'll need to carry out additional steps to define the container for each Product. This helps the JavaScript to smoothly identify relationships between Products, their Prices and their Attributes.

The HTML attribute data-product-group should be added to the highest level HTML element in your Product Layout item.liquid file. Which type of tag this element is doesn't matter- the important thing is that all Prices and Attributes related to this Product are nested inside this element.

If you do not add this Attribute- the JavaScript will treat the Product List like a Detail view- and you may experience unexpected behaviour like all prices changing at once.

Conclusion

This function is useful for updating the displayed price of a Product when new Attribute Options are selected- or removed- by the User / Customer.

While building Product and Attribute Layouts, a large range of dynamic data is available- here is a full reference guide.

"This" Object Fields

The "this" object can be accessed on Product detail/item.liquid, list/item.liquid and attribute layout files. It contains the properties of the current Product and contains further relevant objects e.g. Price.

The entire "this" object can be outputted on the page for reference: {{this | json}} The following fields are available:

Accessing Custom Field Sets

Custom Field Set data linked to Products is available in Product detail/item.liquid, list/item.liquid and attribute layout files.

Any Custom Field Sets that have been associated with the product will be stored under: {{this.cfs_data}}

You can output the above liquid in the item.liquid file to see all of Custom Field Sets associated with the Product. Each of these will have the key "cfs_1", "cfs_2" etc. For example, a developer has created just one Custom Field Set to store information about the Guarantee on the Product. The field can be accessed via: {{this.cfs_data.cfs_1.Guarantee}}

The Price Object

The Price object contains all the information you need to display the Product's price in the format you want. It is available in Product detail/item.liquid, list/item.liquid and attribute layout files.

The Inventory Object

The Inventory object contains the fields related to the current Inventory of this Product. It is available in Product detail/item.liquid, list/item.liquid and attribute layout files.

The Attributes Object

These are available once Attributes have been added against the Product in Admin and you are inside a detail/item.liquid file or an Attribute layout file.

You can access the Attributes Object via the following liquid output: {{ this.product_attribute_options }}

Inside the Attribute Layout

Output Options for this Layout

Inside the Attribute Layout, you can access just the Options for that specific Attribute: {{ product_attribute_options }}

Output this Attribute's Name

You can also access the name of the Attribute this Layout is currently displaying: {{this_attribute.properties.name}}

Looping Over Attribute Options and Accessing Option Fields

As explained in the Attributes Layout Doc, we recommend you loop over the object and access the fields via the "option" liquid variable.

<select name="attr1" class="form-control" data-attribute-control="{{product_attribute_id}}" onchange="s_e_update_price()">
  
{% for option in product_attribute_options %}
    <option value="{{option.id}}" data-attribute-price-control="{{option.price_raw}}">{{option.name}} this.price.currency_symbol}}{{option.price}})</option>
  {% endfor %}


</select>

Assuming the above example liquid forloop has been implemented, you can access the fields in the table below. Remember the "option" liquid variable can be renamed, so if you have done this, replace "option" with the name you have given the variable. The Object contains Attribute Options and each of these contains information on the Attribute it is linked with.

Volume Pricing

Information about how to output information about volume pricing can be found here:

How to use Module Custom Fields to output similar, related products

Pre-requisites

• Your is updated to at least version 1.2.0

• You have already and outputted them in List or Detail Layouts on the Site

Introduction

Module Custom Fields allow a wide range of use cases for connecting up different areas of your Site. In this Article we'll look at how you can create a new Custom Field for your eCommerce products to store similar, related Products which could be displayed on the Product's Detail Page.

You could of course use this same technique with the Blog Module or any other Module or WebApp.

Step 1) Add a new Custom Field to Products

To add a Custom Field to Products, first select Edit Module Structure from the Products List in Admin.

At the bottom of the available fields, you can find the Custom Fields section, and press the "Add new field" button.

The name of your field can be whatever you want, here we'll call it Related Products. The Datasource Multi type prompts us to choose a Module or WebApp that we will be able to select Items from.

When you're ready, press save and your new Custom Field will be set up. You'll then be able to use this field when creating and editing Products.

Step 2) Add related Products to a Product

In this example, we'll edit the new Custom Field on an existing Product to create a relationship with another Product. From the Product Edit Page, select the Custom Fields tab:

As we used the Datasource Multi field type and selected Products as the Module to be linked to, Siteglide knows what we're trying to do and will help us find the related Items.

Select as many as you need. Each Product's unique ID will be stored in array format in your Custom Field.

When you're ready, save the Product.

Step 3) From the Product Detail Layout access the Related Product IDs

For the next steps (3 - 6), we'll be navigating to Code Editor to develop custom Layouts to display the Related Products Front End. We'll start by working in the "item.liquid" file of the Layout you're using for the Product Detail View. We'll nest a new List of Related Products inside this Detail Layout.

Inside the item.liquid file, we can access the Custom Field by name:

<h2>Related Products</h2><br><br>
{{this['Related products']}}<br><br>

This outputs an array of the IDs of each of the related Products stored against our current Product. It should look something like this: ["55","75","147"]

Step 4) Convert the Related Product IDs to a comma-separated String format

In Step 5, we'll need to nest a new List Layout of Products inside the Detail Layout and filter this by the IDs of our Related Products. However, the IDs are currently in an Array format and the include Liquid tag's item_ids parameter expects a comma separated String.

We can change the type by assigning a new variable:

{% assign related_products_str = this['Related products'] | join: ',' %}

Step 5) Add a Product List Layout which Datasources to the Related Products

Next, we need to output a Product List, nested within our existing Product Detail Layout.

<h2>Related Products</h2>



{%- include 'ecommerce/products'
    layout: 'default'
    per_page: '3'
    show_pagination: 'false'
    sort_type: 'properties.name'
    sort_order: 'asc'
    datasource: 'true'
    item_ids: related_products_str
-%} 

Item Ids Parameter

Without the item_ids parameter, our List outputs only the first few Products alphabetically, instead of fetching our dynamic Related Products.

We can change that by adding the item_ids parameter and feeding in our comma-separated String of IDs (that we stored in a new Liquid variable):item_ids: related_products

Datasource Parameter

datasource: 'true' When you output an include inside a Detail Layout, by default Siteglide will try to fetch a Detail Layout. This is one reason why it's important to set the datasource: 'true' parameter, which will then cause Siteglide to look for a List type Layout.

Another benefit of the datasource: 'true' parameter is that if no Related Product IDs are available, the List will return empty, instead of returning an unfiltered List. This prevents the List from showing unrelated Products in this situation.

Per Page Parameter

per_page: '3' In the example, the per_page has been set to 3. In some cases, you may wish to limit the number of "related" results in this way, so they don't distract from the main subject of the Page. It is completely optional.

Layout Parameter Select the name of a Product List Layout you'll use to style how the dynamic Related Products List will look (see Step 7).

Step 6) Hide content when no Related Products exist

Optionally, you can add Liquid logic to only display the subtitle and Related Products content when the field is not empty. As the field contains an array, a safe way to check if it holds a value is to check its size (Liquid for the length of the array).

{% if this['Related Products'].size > 0  %}
  <h2>Related Products</h2>
  {% assign related_products = this['Related Products'] | join: "," %}
  {%- include 'ecommerce/products'
      layout: 'default'
      per_page: '3'
      show_pagination: 'false'
      sort_type: 'properties.name'
      sort_order: 'asc'
      datasource: 'true'
      item_ids: related_products 
  -%} 
{% endif %}

Step 7) Optional - Develop a Custom Layout for the Related Products

You've now completed the Step by Step guide for adding Related Products.

📂 Discount Selection

Introduction

We're introducing Discount Codes to our eCommerce Module.

Your Client will be able to define and manage codes in the Admin- and manage their offers by setting the release and expiry dates, as well as the maximum number of uses in advance.

You'll be able to implement options in the Cart and Checkout for entering discount codes and the Module will work out the discounted costs for you.

Managing Codes in the Admin

You can see a list of all Discount Codes under the eCommerce Menu.

Available Fields

You can set the following fields when you create or edit a Discount Code:

• Item Name - Gives the discount a name

• Weighting - (optional) - Used in sorting

• Release Date - When should the discount code start being valid?

• Expiry Date - When should the discount code stop being valid?

• Enabled - Should the discount code be enabled or disabled?

• Code - A String of characters for the code a customer will need to enter for - the discount to be valid.

• Type - Should the discount be a percentage of the total Cart value, or a fixed - amount?

• Discount Value - How much of a discount should be given when this code is - entered? Choose a value appropriate to the type you selected e.g. 20 for 20% - or 20.00 for $20.00

• Minimum Spend - Often your Client will want to use the offer to up-sell to the - customer. By setting a minimum spend, the customer will need to spend this - amount before the offer can be used. The offer will apply to the entire value - of the Cart still, not the difference between the minimum spend and the Cart - value.

• Uses Remaining - This sets a total number of uses before the offer - automatically expires. This does not measure the number of times an individual customer uses the offer, rather it measures the number of times the offer has - been used globally. If your Client does not want to set a limit, you can set a - very large number- or your Client can increase the number when it runs low.

• Valid on Payment Form Type - Choose 'Checkout' (default), 'Basic Payment' or 'Subscription'. The discount code will only be applicable to the specified - Form type. This is useful when you have both Checkout Forms and Basic Payment Forms on your Site with different purposes.

Special Fields for Subscriptions Discount Codes

When "Valid on Payment Form Type" is set to "Subscription", a "Coupon" will be created on the connected Stripe account. Therefore, extra fields are needed for this type:

• Number of Months to Discount - Even if your Subscription's Interval is days or weeks, this field must be measured in whole months. The discount will apply to - every invoice until the months are finished, after which the price will revert - to the price defined in the Subscription's plan.

• Stripe Coupon ID - This field will be filled automatically. You can use it to look up the associated Coupon in the Stripe Dashboard.

Create a New Discount Code

From the List View, you can create a new Discount Code.

Edit an Existing Discount Code

Find your code in the List, and use the pencil icon to edit.

Delete a Discount Code

From the Edit screen, you can delete a Discount Code.

Orders

If customers have used a Discount Code to make a purchase, you'll be able to see this against their Order. You can see customers' Orders under the eCommerce Menu in Admin.

Adding an Input Field for Codes in the Cart Layout

In the next Article, we'll show you how to add and develop a Discount Codes Layout.

This will allow Users to type in and apply a Code, or remove a Code if it no longer applies and is preventing them from checking out:

Products in eCommerce are where you can add and manage your own products and services with ease.

Here, you can add new products; import and export these; add attributes; control inventory and much more.

Where can you find Products?

While viewing your Site Admin, use the left-hand menu to click "eCommerce" and expand the sub-menu. Next, click on "Products" to view a list of Products on your Site.

This Article explains how to output a Discount Codes Layout in either Basic Payment Form, Cart, Checkout or Subscription Layouts

Introduction

Discount Codes allow your Client to provide special offers to their customers.

You can learn how to set up Discount Codes in the Admin here.

The role of a Discount Code Layout is to give the customer an opportunity to enter and apply a Discount Code on your Site. Additionally, once a code is applied, the Layout will give the customer information about how their code has been applied along with any terms and conditions, and the opportunity to remove the code.

This Article will explain how you can include a Discount Codes Layout in either your:

• Cart wrapper.liquid file

• Checkout Form Layout (Discount Code Layouts for the Cart and Checkout will have the same syntax).

• Basic Payment Form Layout - This will have slightly different syntax due to the unique properties of Basic Payment Forms, but we'll cover this below.

• Subscription Form Layout - This will have slightly special considerations because the discount has the potential to be applied to all invoices for a specified number of months. It's also possible to use Subscription Discount Codes to take 100% off the price giving a free trial.

Once a customer uses the button in the Layout to successfully add a Discount Code, this will be stored in their session alongside any Cart Data. We'll store one code at a time for each payment type, with Basic Payment Forms storing their codes in {{context.session.basic_payment_discount}}, Cart saving its codes in {{context.session.cart_discount}} and Subscriptions saving their codes in {{context.session.subscription_discount}}.

When a customer completes a Payment Form, the Server-side checks will apply the code and reduce the amount they are charged. This means your Site will be secure and safe against malicious users choosing their own discounts.

Step 1 - Including the Layout inside the Cart, Checkout, Basic Payment Form or Subscription Form Layout

The screenshot below shows how the Discount Code Layout can be nested inside the Cart. However, step 1 also applies in all kinds of Layout.

1a - Add your Layout

The following Liquid will add the Layout:

{% include 'ecommerce/discount_code'
   layout: "cart/default" 
%}

The only parameter you'll need will be layout which refers to the file name of the Layout. We'll look at where to create the Layout files in Step 2.

1b - Optional - Adding Support for Refreshing Layout instead of whole Page

In order to better support adding Discount Code Layouts on Forms, we've added the option to reload just the Layout, instead of the whole Page. The main benefit of this is that Users will not have to refill their form data after adding a Discount Code. We'll discuss this more in Step 3) b)

For now, you can add the data-attribute data-s-e-refresh-layout-discount-code to the element which serves as a wrapper for your Layout e.g.

<div data-s-e-refresh-layout-discount-code>
{% include 'ecommerce/discount_code', layout: "cart/default" %}

</div>

In a Cart Layout, you may also wish to set prices to automatically update when the discount code is added.

You can add the following data-attributes:

• data-s-e-live-cart-currency - the element will be filled dynamically with the Cart currency when the Layout refreshes

• data-s-e-live-cart-total - the element will be filled dynamically with the updated Cart Total Price.

e.g.

<p class="text-uppercase"><strong>TOTAL PRICE:</strong> 
<span data-s-e-live-cart-currency></span>
<span data-s-e-live-cart-total>
{% include 'ecommerce/price_total'
            format_type: 'formatted' -%}</span></p>

Related Layout Development Docs

• Developing Cart Layouts

• Checkout Tutorial

• Basic Payment Form Tutorial

Step 2 - Create Layout Files or Choose the Discount Code Layout

A Discount Code Layout will typically contain:

• An input field for the customer to enter a discount code

• A button which allows them to submit the code

• A button which allows them to remove a code (if perhaps the code is no longer valid and blocking payment).

• Feedback to the user regarding successful and unsuccessful attempts to apply their discount code.

• Essential HTML, JavaScript and Liquid which controls functionality

File Structure

Discount Code Layouts will be stored here, inside: layouts/modules/module_14/discount_code

You'll just need a single Liquid file with the same name as your Layout. Optionally, you can use folders to organise Layouts of different types.

If you haven't already, make sure your layout parameter in the Liquid tag matches the name of your Layout File. Any custom folders like 'cart/' should also be added to the layout parameter path.

As there are subtle differences in implementation depending on the type of payment, we've created three different default layouts to help you get started:

• "basic_payment/default"

• "cart/default"

• "subscription/default"

For steps 3 and onwards, you may find it easier to copy and edit the code from the default Layout, but we'll break this down into steps here so you can see all the elements you'll need.

Step 3 - Add HTML and Liquid to allow a Customer to enter a Discount Code

3a - Add an <input> element and <label>

<label class="mb-3" for="s_e_discount_code">Discount Code</label>
<input class="form-control" 
       id="s_e_discount_code" 
       data-s-e-discount-code 

{% if discount_code != blank %} 
       value="{{discount_code}}" 
       readonly="true"{%- endif -%}

HTML Attributes Explained:

| If a code is already successfully added, it will be autofilled. or Any successful code is autofilled and the current field value is readonly until removed in step b) | One of these |

3b - Add an "Apply" button

When adding the 'Apply' button, you can customise how the JavaScript will behave on successful and unsuccessful attempts to add a Discount.

In the examples below, we'll show the basic options recommended for different types of Layout, then explain the full range of options you have for JavaScript behaviour.

Applying to a Cart Layout:

<button class="btn btn-primary sg-btn sg-btn-primary" 
        id="s_e_discount_apply" 
        onclick="s_e_cart_discount_code(
{
  spend: '{{context.exports.cart_base_price.data | json}}',
  reload: true
  
}
)">Apply Code</button>

Applying to a Checkout Form Layout:

<button class="btn btn-primary sg-btn sg-btn-primary" 
        id="s_e_discount_apply" 
        onclick="s_e_cart_discount_code(
{
  spend: '{{context.exports.cart_base_price.data | json}}',
  reload: false
}
)">Apply Code</button

Applying to a Basic Payment Form Layout:

<button class="btn btn-primary sg-btn sg-btn-primary " 
        id="s_e_discount_apply" 
        onclick="s_e_cart_discount_code(
{ 
  spend: document.querySelector('#s_e_amount').value,
  reload: false
}
);">Apply Code</button>

Applying to a Subscription Layout:

<button class="btn btn-primary sg-btn sg-btn-primary" 
        id="s_e_discount_apply" 
        onclick="s_e_cart_discount_code(
{
  spend: {{spend}},
  reload: false
}
);">Apply Code</button>

3c - JavaScript Options Explained

At this stage, you have a choice about whether you'd like the whole Page to reload after a successful Discount Code is added, or whether you'd like to only reload the Discount Code Layout itself.

We'd strongly recommend that for Layouts on Forms that you set reload: false as this will prevent the User having to re-enter their Form data, and will preserve any custom amount chosen on the Basic Payment Form.

Note also that the value of spend will be different for Basic Payment Forms:

• Basic Payment Forms store the spend value in document.querySelector('#s_e_amount').value - as this can be dynamically changed by JavaScript, there is no Liquid value for it.

• Cart and Checkout Forms can use the Liquid value: '{{context.exports.cart_base_price.data | json}}'

• Subscriptions store the spend in {{spend}}

Step 4 - Add HTML and Liquid to allow a Customer to Remove a Discount Code

You can optionally add a button to the Layout which will allow the customer to remove a Discount Code that has already been applied.

{%- if discount_code != blank -%}
  <button class="btn btn-danger" id="s_e_discount_remove" onclick="s_e_cart_discount_code_remove(
    {
      reload: false
    }
  )">
    Remove Code
  </button>
{% endif %}

The Liquid IF statement helps make sure the button is only displayed if there is a code present to be removed.

The JavaScript function will make the button functional.

Why is this helpful? Although we check Discount Codes are valid when they are added, there are cases where the code is no longer valid by the time the customer reaches the Checkout, for example:

• The User may have adjusted the quantity of items in the Cart, causing the spending amount to drop lower than the minimum payment allowed by the Discount Code.

• The Code may have been close to expiry.

Adding a "remove" button gives the User a clear way to solve any problems stopping them from completing their purchase.

Step 5 - Add HTML and Liquid to give the customer feedback

5a - Displaying the Discount Amount

On Page refresh (or if you've chosen reload: false on Layout refresh), after a successful Code is applied, the following Liquid will explain the minimum spend needed and the discount available.

Depending on where your Layout is, different syntax may be needed to fetch the currency to display.

On Cart and Checkout Layouts:

{% if discount_code != blank -%}
<p>Discount: 
    <span style="color: red;">
        -{{context.exports.cart_currency.data}}
        {%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter'
                     price_data: discount_amount -%}
                     </span>
                     </p>
                     {% endif %}

On Basic Payment Layouts:

{%- if discount_code != blank -%}
<p>Discount: 
    <span style="color: red;">
        -{% include 'ecommerce/basic_payment_currency'
                     format: 'symbol' %}
                     {%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter'
                                  price_data: discount_amount -%}
                                  </span>
                                  </p>
{%- endif -%}

On Subscription Layouts:

On Subscription Layouts it is important to know whether or not the Subscription Order has been created, if it has, then the Discount will already be redeemed. The difference in display needs to account for the fact that a redeemed discount is time-limited.

For both situations, we can use the fields inside the discount variable to access details on the Discount.

Before the Subscription Order is Created At this stage, we can use general details of the discount which is applied, but not yet redeemed, from the this object.

{%- if discount_code != blank -%}
  <p>Discount: 
  <span style="color: red;">
    -{{this.price.currency_symbol}}
    {%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter'
                 price_data: discount_amount -%}
                 </span>
  every 
    {% if this['Interval Count'] != "1" %}
      {{this['Interval Count']}} {{this['Interval']}}
    {% else %}
      {{this['Interval'] | pluralize: 1}}
    {% endif %}
    for {{discount.number_of_months_to_discount}} 
    {% if discount.number_of_months_to_discount == 1 %}
      month
    {% else %}
      months
    {% endif %}
  </p>
{%- endif -%}

After the Subscription Order is Created and the Discount Redeemed At this stage, we can use details of the actual discount code stored against the Subscription Order. As this is time limited, we may also wish to give details of how much longer the Discount will be active for and the specific Subscription Order will provide these details.

{%- if discount_code != blank -%}
  <p>Discount redeemed: 
    <span style="color: red;">
      {{this.price.currency_symbol}}
      {%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter'
                   price_data: discount_amount -%}
    </span> saved every 
    {% if subscription_order['Plan Interval Count'] != "1" %}
      {{subscription_order['Plan Interval Count']}}
      {{subscription_order['Plan Interval']}}
    {% else %}
      {{subscription_order['Plan Interval'] | pluralize: 1}}
    {% endif %}
    for {{discount.number_of_months_to_discount}} 
    {% if discount.number_of_months_to_discount == 1 %}
      month
    {% else %}
      months
    {% endif %}
    until {{subscription_order['Plan Discount Ends At'] | date: "%d/%m/%y"}} 
  </p>
  <p>Total Due: {{this.price.currency_symbol}}
    {%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter'
                 price_data: discount.total_remaining -%}
                 </p>
{%- endif -%}

5b - Displaying the Minimum Spend

The following code can be used to display the minimum spend needed to keep using the discount:

On Cart and Checkout Layouts:

{%- if discount_code != blank and discount_minimum -%}
<p class="mt-4">
    This code will only be valid on Cart orders worth over: 
    {{context.exports.cart_currency.data}}
    {%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter'
                 price_data: discount_minimum -%}</p>
{%- endif -%}

On Basic Payment Layouts:

The following code can be used to display the minimum spend needed to keep using the discount:

{%- if discount_code != blank and discount_minimum -%}
<p class="mt-4">
    This code will only be valid on orders over: 
    {% include 'ecommerce/basic_payment_currency'
                format: 'symbol' %}
                {%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter'
                             price_data: discount_minimum -%}
                             </p>
{%- endif -%}

On Subscription Layouts

It's probably only really necessary to display the minimum spend before the Subscription Order is created and the Discount redeemed. Once the discount is redeemed, the amount spent will be fixed.

{%- if discount_code != blank and discount_minimum -%}
  <p class="mt-4">
    This code will only be valid on orders over: 
    {{this.price.currency_symbol}}
    {%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter'
                 price_data: discount_minimum -%}
                 </p>
{%- endif -%}

5c - Displaying a Message when the Discount Maximum is Reached on Basic Payment Forms, Cart and Checkout

This code will display a message if the minimum spend is not set strictly enough and the resulting payment total is below that allowed by the Payment Gateway.

{%- if discount_saving_maximum_reached == true -%}
<!-- Message here -->
<p class="mt-4">
    Minimum transaction value reached. 
    To make the most of your discount, try adding another item to your Cart.</p>
{%- endif -%}

discount_saving_maximum_reached will always return false for Subscriptions and these allow any size of Discount (controlled only by the Partner and Client setting Minimum Spend values on each Discount Code in the Admin.) Therefore, it's not necessary to add this code to a Discount Code Layout for a Subscription.

Read more about the Discount Maximum requirement

Summary of Available fields when building your Discount Code Layout:

• discount_code is a variable which contains the Discount Code successfully applied after page refresh

• discount_minimum is a variable which contains the minimum spend needed for this Discount Code to be valid.

• discount_amount is a variable which stores the calculated saving on the current Cart value.

• {{context.exports.cart_currency.data}} will output the currency symbol on Cart and Checkout Layouts

• {% include 'ecommerce/basic_payment_currency', format: 'symbol' %} will output the currency symbol on Basic Payment Layouts

• `{%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter', price_data: discount_minimum -%}

You can use this Liquid tag to format any Liquid price variable with the correct decimalisation. To use, set theprice_data` parameter to the variable you wish to format.

• discount_saving_maximum_reached - if true, the Minimum Amount for the Discount Code has not been set strictly enough and the total Payment Due is below that allowed by the Payment Gateway. You can use this to display a warning message that it has not been possible to apply the full discount.

• For Subscriptions, your Layout will inherit the variables of the Layouts it's nested within- meaning it will inherit variables from the Subscription Detail Page, then the Subscription Form. See details of these objects here. e.g. {{this.price.currency_symbol}}

Step 6 - Optional - Add JavaScript to handle errors

There are lots of reasons why the customer may enter a code but be refused a discount. For example, the code may have expired, or the Cart's value may not be above the minimum spend.

You can start with the JavaScript function below and make your own changes to decide how these errors are displayed to the customer:

function s_e_discount_error(error) {
console.log(error.type); 
/* an error code which you can use in your logic. */
console.log(error.message); /* A ready-drafted error message */
alert(error.message);
}

As the comments in the example mention, each error returned from a failed discount code will give both a code and a default message. You can choose which one you will use.

Here are the full list:

If you want to change the message, you can use logic to display different messages using the error code:

<script>
function myErrorFunction(error) {
if (error.type == 'no_code' ) {
alert('Better luck next time. Discount Code not found!');
} elsif (error.type.indexOf('below_min_spend=') != -1 ) {
//As the below min_spend code can vary depending on the value, this code checks for the substring.
alert('You'll need to spend more before using this code.');
}

</script>

Once you've created your function, use the error_cb option in step 3) b) and pass it your function name. e.g. error_cb: myErrorFunction

Step 7 - Optional - Customise the JavaScript behaviour when a code is successfully added

Setting reload to either true or false in the s_e_cart_discount_code function will both effectively refresh your Discount Code Layout and the Liquid will update with new values, so most use-cases will not need a custom success function. However, if you do need to make changes, you can use the function below as a starting point:

function mySuccessFunction(reload = true, discount, payment_type, refreshed_discount_layout) {
if(reload == true) {
window.location.reload();
} else if (refreshed_discount_layout) {
var slot = document.querySelector('[data-s-e-refresh-layout-discount-code]');
slot.innerHTML = refreshed_discount_layout;
if(payment_type == 'Checkout') {
s_e_cart_update_prices();
}
}
}

Available arguments:

Once you've created your function, use the success_cb option in step 3) b) and pass it your function name. e.g. success_cb: mySuccessFunction

Step 8 - Optional - Customise the JavaScript behaviour when a code is successfully removed

Setting reload to either true or false in the s_e_cart_discount_code function will both effectively refresh your Discount Code Layout and the Liquid will update with new values, so most use-cases will not need a custom success function. However, if you do need to make changes, you can use the function below as a starting point:

function mySuccessFunction(reload = true, payment_type = 'Checkout', refreshed_discount_layout) { 
if(reload == true) { 
window.location.reload(); 
} else if (refreshed_discount_layout) { 
var slot = document.querySelector('[data-s-e-refresh-layout-discount-code]'); 
slot.innerHTML = refreshed_discount_layout; 
if(payment_type == 'Checkout') { 
s_e_cart_update_prices(); 
} 
} 
}

Available arguments:

Once you've created your function, use the success_cb option in step 3) b) and pass it your function name. e.g. success_cb: mySuccessFunction

Specific Instructions for Subscriptions

At this point it's not possible to apply or change the Discount Code, only display details of the Order that's active. The purpose of the Form at this point is actually to allow Users to edit their payment details only.

{% if subscription_discount_already_redeemed == true %}

<!-- Insert code here - the Discount has already been redeemed against the Subscription Order-->
{% endif %}

You could add this logic around the whole Layout (as in the default Layout), or just around individual components. For the sake of clarity, in the "subscription/default" Layout, we've opted to wrap the logic around the whole Layout, creating two distinctly separate blocks of Liquid for before and after redemption.

You can also add the statement to check if the Discount will apply to the next invoice or if the Discounted period of months is over.

{% if rate_still_discounted == true %}
{% endif %}

Shipping Options let customers choose how fast they'd like eCommerce Products delivered and prices are added onto the price at Checkout.

Introduction

Shipping Options let customers choose how fast they'd like eCommerce Products delivered and prices are added onto the price at Checkout.

Here's what it does:

• Admin Users can add and remove Shipping Options e.g. "Free Delivery", "Premium"

• You can output the Shipping Options in your Cart with their own sub-layout

• Once chosen, the Shipping Option will be saved alongside the customer's Cart and the price of shipping will be added to the total price displayed.

• When an Order is made, the customer will pay for the price of Shipping and the option chosen will be displayed against their Order in the Admin.

Managing in the Admin

You can add, edit and remove Shipping Options in the Admin. Go to ECOMMERCE/Shipping Options in the left-hand menu.

Including the Options

The Options are designed to be included in an HTML Select box in the Cart.

Syntax

You'll need to add the following Liquid where in your Cart you want to include your Shipping sub-layout:

{% include 'ecommerce/shipping_option', layout: "siteglide_example" %}

The only parameter you'll need to include is your Layout.

You won't need to do anything else to implement this feature. Any options selected by the customer will have their prices added to the price total in Checkout.

Custom Layouts

File Structure

Include your Custom Layout alongside my_layout:

• layouts

  • modules

    • module_14 (eCommerce)

      • shipping_option

        • siteglide_example.liquid

        • my_layout.liquid

Here's an example:

<div class="form-group">
	<select onchange="s_e_cart_shipping(this);">
		<option value="">--Please select--</option>
		
{%- for this in shipping_options -%}
			{% assign currency = this.price.properties["module_field_14/price_2"] %}
			<option {% if this.id == current_cart_shipping_id %}selected{% endif %} 
					value="{{this.id}}">{{this.name}} {{this.currency_symbol}}{{this.price}} 
					</option>
		{%- endfor -%}
	</select>
</div>

Some key points to note from the example:

• You'll need to put the onchange attribute on the HTML Select element itself and use the Siteglide function.

• You'll need to loop over the shipping_options array we've created for you to build your HTML Option elements.

• You can use a Liquid if statement to mark an option as the Shipping Option currently selected by the User: `

`

Introduction

Discount Codes can cause the payment total due to be smaller than your Client may wish- or even 0.

When accepting payments, most Clients won't want to handle very small payments e.g. less then 50 cents.

Why are small charges a problem?

Stripe's payment gateway will, in fact, refuse to process payments smaller than its minimum payment amounts, which will lead to bad User Experience as Payments will fail.

PayPal will accept these small payments, but will charge the Client potentially more than they make on the transaction.

The solution for Basic Payment Forms and Checkout

This Article will explain the two main solutions to these small charges:

• Recommended - The Agency and Client can set Minimum Spend against each discount Code

• Fallback - While applying discounts, Siteglide rounds payments up to an absolute minimum the Payment Gateway will accept.

In the future, we plan to change the flow so that Siteglide will accept 100% discounts in the Checkout by skipping the Payment step. For now- we'll recommend alternatives if you need this functionality.

Avoiding Small Charges

In the following section, we'll refer to the "minimum desired spend". By this, we mean either:

• The lowest value order your Client is willing to accept (bearing in mind they still need to pay the charges due to the Payment Gateway on this Order).

• If using Stripe, this will be at least 50 of your currency's lowest denomination e.g. cents

• If using PayPal, this will be at least 1 of your currency's lowest denomination e.g. cents.

Setting the Minimum Spend as the Agency or Client

The main method the Agency and Client have at their disposal to prevent this is the Minimum Spend field when creating or editing their Discount Codes.

This field should be set up to make sure that if it's value has the discount applied, the total price due would still exceed the minimum desired spend.

E.g.

For percentage discounts - you should check that if the percentage discount is applied to the value in "minimum spend" it won't leave a total which is lower than the minimum desired spend:

e.g. In this example, let's assume it's only economically viable for the Client to accept spends of 50 cents or more- this is their "Desired Minimum Spend" (your Client's may well be different!).

In the screenshot below- even with a 90% discount, the minimum spend is high enough to avoid excessively small charges:

$5.00 multiplied by 90 divided by 100 is a saving of $4.50.

$5 dollars with a $4.50 dollar discount leaves a remaining payment due of $0.50.

For value discounts the calculation is simpler - "Minimum spend" minus "value" should be greater than minimum desired spend.

E.g. For a $9.50 discount, you need a "Minimum Spend" of $10 to prevent discounts from allowing a spend below $0.50.

As explained below, Siteglide will take its own steps to avoid very small charges, but using the Minimum Spend field is the easiest way to make these limits clear to Users, improving their experience. It also allows the Client to decide if their minimum desired spend is greater than the Payment Gateway's value.

How Siteglide Handles Small Charges on Basic Payment Forms and Checkout While applying discounts, Siteglide will automatically check if the total price due is below the absolute minimum needed for the Payment Gateway to accept the Payment.

If this is the case, Siteglide will automatically adjust the total price due to:

For Stripe, 50 of your currency's lowest denomination e.g. cents For PayPal, 1 of your currency's lowest denomination e.g. cents This will display on the Cart, and be the total amount actually charged to the User's Card.

Informing Users

Again, setting a reasonable Minimum Spend is the preferable solution to this issue, but in the case that Siteglide does need to fall-back and round charges up to the minimum payment, you can inform the Users of this with a message.

This code can be used inside your Discount Code Layout:

{%- if discount_saving_maximum_reached == true -%}<!-- Message here --><p>Minimum total price reached. Unfortunately we cannot accept payments below this price. To make the most of your discount, try adding another item to your cart.{%- endif -%}

Subscriptions

Stripe Subscriptions handle this problem differently. The variable discount_saving_maximum_reached will always return false for Subscriptions discounts, as we will never manually cap the amount of Discount for these kinds of payment.

Firstly, Subscriptions allow you to give 100% discounts- this effectively creates one form of "free trial".

Secondly, if Stripe judge a Subscription invoice to be for an un-economically small sum, they will carry that charge over to the next invoice. In the same way, if the discount gives a greater reduction in cost than the spend, the customer will receive credit in the Stripe account, which will be carried over into the next invoice. If you do not wish for this behaviour, see Setting Minimum Spend above!

What if I actually want to apply 100% discounts on Basic Payment Forms and Checkout?

Currently, it is not possible to offer 100% discounts on Checkout using Stripe or PayPal.

In the future, we intend to better support 100% discounted Orders by completing the Order without carrying out a Payment, however, we expect values between 0 and the Payment Gateway's minimum to continue to be rounded up.

The following alternative Form types do currently allow Users to complete them with Payments of 0:

Our Quote Only feature for these customers- as this does allow Orders to be created without any charges being made- meaning the Client will not be charged. Our Basic Payment Form with Stripe will already skip payment if the amount due is exactly zero and the Minimum payment value field attached to the Form in Admin is also 0.

Whilst editing a Product, navigate to the "Location" tab.

Here you can manage and edit the address and longitude/latitude fields.

Using one of the two methods:

• Search for an Address - Search for an address that you'd like to use, and select from the results in the dropdown

Or

• Address - Manually enter the address in text form, and

• Longitude/Latitude - GeoJSON - enter the address as coordinates [long, lat]

Once you have done this, click save; and head over to our Location docs to set this up.

Customise the "Add to Cart" button to keep customers on the Page or redirect them straight to the Checkout Flow with a "Buy Now" button.

Prerequisites

This Article assumes you've already:

• Added a "cart_add" button to a Layout.

If you've not already done this, you can read the following Articles to learn more:

• Product List Layouts

• Product Detail Layouts

Introduction

Although we've had an "Add to Cart" button for a while now, we've recently added the ability to add a custom Layout for this component.

This will allow you to:

• Change the style of the button

• Change the style of the button when the Product is out of stock

• Change the behaviour of JavaScript when adding to the Cart is successful

Specifying a Layout

You can add a Layout to the Cart Add Button by adding a component_layout parameter to the Liquid:

{% include 'ecommerce/cart_add', component_layout: 'custom_layout' -%}

This feature is backwards compatible, so if you have a Site which does not specify a Layout for these buttons, the default Layout will be chosen automatically- and this will be identical to the style and behaviour you are used to.

Layout Files

We store these Layout files at the following path: layouts/modules/module_14/components/add_to_cart_button/my_custom_layout.liquid

You can either edit the default Layout or create your own by right-clicking on the "my_custom_layout" folder.

Code

Looking at the default layout, you can see that it has some key characteristics you may wish to keep in your new Layout:

• Checking if the Product is in stock

• Running the JavaScript function

Checking if the Product is In Stock (or no inventory limit is set)

You can use a Liquid If Statement to check if the Product is in stock.

{% if this.inventory.id == blank or this.inventory.quantity != '0' -%}
  <!-- Product is in stock - or no inventory limit is set.-->
{% else -%}
  <!-- Product is out of stock. -->
{% endif -%}

Running the JavaScript Function

To achieve the functionality of adding a Product to the Cart, you'll need to run a JavaScript function when the button is clicked. The first argument is mandatory- you must pass in the ID of the Product using Liquid: onclick="s_e_cart_add({{this.id}})"

Customising the Success Alert

Adding your own Function

The second argument in the JavaScript function is optional. If you like, you can add in the name of a function you've defined on your Page. This will run instead of the default "alert" message when a Product is successfully added:

<button class="btn btn-primary" 
        onclick="s_e_cart_add({{this.id}}, my_success_function)">Add to cart</button>

<script>
  function my_success_function() {
    alert('Ajouter au Panier.');
  }
</script>

As in the example above, you can use this to add a different alert message with a different message. Or you could run any other JavaScript you like instead.

Customising the Success Alert along with Live Cart Update

Remember, you also have access to the function: s_e_live_cart_update()which will return the number of Items now in the Cart. You could incorporate this number into the message.

<button class="btn btn-primary" 
        onclick="s_e_cart_add({{this.id}}, my_success_function)">Add to cart</button>

<script>
  function my_success_function() {
    var cartTotal = s_e_live_cart_update();
    alert('Success! You now have '+cartTotal+' items in your Cart');
  }
</script>

Buy Now Button

Some eCommerce Sites require a "Buy Now" button which adds the Product to the Cart and then sends them directly into the Checkout Flow. You can turn your "Add to Cart" button into a "Buy Now" button using customisation options:

<button class="btn btn-primary" 
        onclick="s_e_cart_add({{this.id}}, my_success_function)">Buy it now!</button>

<script>
  function my_success_function() {
    window.location.href = "/cart";
  }
</script>

Product Attribute Layouts allow you to customise the way that you present users with a choice of which variation of a Product they want.

Product Attribute Layouts allow you to customise the way that you present users with a choice of which variation of a Product they want.

Prerequisites

• You have created Products in the Admin

• You have created a Product Detail View

Introduction

This Tutorial will show you how to use Attributes to let Users pick Variants on the Product's automatically-generated Detail Page.

It will cover how to:

• Find where Product layouts are stored on Code Editor

• Develop a my_attribute_layout.liquid file

• Allow the User to select Attribute Options before adding to Cart

Folder Structure

In SITE MANAGER/Code Editor, the folder structure for product attributes layouts is as below:

marketplace_builder
└───views
    └───partials
        └───layouts
            └───modules
                └───module_14
                    ├───product
                    │   collection.liquid
                    │   └───custom_product_layout
                    │       ├───detail
                    │       │   item.liquid
                    │       │   wrapper.liquid
                    │       └───list
                    │           item.liquid
                    │           wrapper.liquid
                    └───product_attributes
                        └───custom_attributes_layout.liquid

See a more complete Cart & Checkout Folder Structure here:

Creating a new set of Product Layouts

To create a new set of Product layouts- create your folder at the level of "name_of_my_layout". Inside that, the folders and files should be created as shown above.

Including a Single Known Attribute on a Detail Page

If you are making a layout where you know exactly which Attribute a Product has, you can include an Attribute layout to display an Attribute with a given name: detail/item.liquid (including a single Attribute)

{% include 'ecommerce/product_attributes'
   name: attribute
   layout: 'demo_site_attributes'
   attribute_name: "Size" 
-%}

Looping Over Multiple Attributes

If your Products have multiple Attributes, or you want to write code which can dynamically display any Attribute given to the Product, you can use liquid to loop over all Attributes. We've recently updated this example to be much simpler and easier to use.

Steps:

1. Loop over all Attribute Options

2. Check if the Attribute is enabled

3. If so, include the relevant Attribute layout, dynamically filling in the "name" parameter.

Full example:

detail/item.liquid -- (looping over all Attributes linked to this Product)

{% for attribute in this.product_attributes %}
  {% if attribute.properties.enabled == true %}
    {% include 'ecommerce/product_attributes'
       name: attribute.properties.name
       layout: 'demo_site_attributes' 
    -%} 
  {% endif %}
{% endfor %}

Attribute Layout Development

There is no need to create a wrapper file for Attributes, as they are already included inside an item.liquid file. Your Attribute layout can be given a name of your choice. Different Attributes for the same Product may use different Attribute layouts, e.g. "Colour" may include colour swatches.

You can output the name of the Attribute that the current Layout displays: {{this_attribute.properties.name}}

The following liquid outputs an array of the options that have been created for this Attribute: {{product_attribute_options}}

You can loop over this array with the following liquid code, (where the example has the variable "option", you could choose any variable name):

{% for option in product_attribute_options -%}
  {{option.name}} ({{this.price.currency_symbol}}{{option.price}})
{% endfor %}

To get the full benefits of Attribute functionality, including the user's choice of Attribute affecting what is added to the Cart, the data-attributes and function calls in the example should be included:

<select name="attr1" class="form-control" data-attribute-control="{{product_attribute_id}}" onchange="s_e_update_price()">
  
{% for option in product_attribute_options %}
    <option value="{{option.id}}" data-attribute-price-control="{{option.price_raw}}">
      {{option.name}} {{this.price.currency_symbol}}{{option.price}})
    </option>
  {% endfor %}
</select>

As you can see in the example, inside the loop it is possible to access the specific Attribute Option in this iteration via the "option" variable you created when setting up the loop, but you can also still access the "this" object specific to the Detail Layout that wraps around and includes the Attribute Layout. See the Product Layout Liquid Reference to see the fields available in the "this" object and those specific to Attributes and Attribute Options.

Importing Products enables you to add Products in bulk at the same time. This is handy when you have many Products that you'd like to add or you'd like to edit these items in mass. Exporting enables you to generate a copy of your items and download this to your computer.

Where do you begin?

Firstly, navigate to your Products.

Above your list of Products, you'll see two blue buttons that say "Import" and "Export".

How do you import?

You can import data to Products, either by creating your own CSV file using the correct column headers or by downloading the import template and populating it with data. Click "Import" to redirect you to an area where you have two tabs, "Prepare" and "Start Import".

Clicking on "Prepare" will enable you to create your own CSV file using the correct column headers or by downloading the import template and populating it with data.

Start Import

Click on "Start Import" when you have a CSV file prepared, and click "Select CSV" to choose your file and begin importing into Siteglide.

A success message will show in the top right hand corner when this process has been completed for you. You can also head to Site Manager > Import Logs, to find a log of this CSV import.

How do you export?

To export your Products, click the blue button that says "Export". A background data export process is then triggered, and you will receive an email when the data is ready for you to collect.

You can track progress of all your exports via Site Manager > Export Logs. Here you can see all exports that have been triggered, and download the resulting data.

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.

<button class="btn btn-success" 
        onclick="s_e_cart_inventory_check({checkout_url: '/checkout'})">
        Confirm and Checkout
        </button>

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:

<p data-s-e-cart-has-removed-products>
{% if context.session.cart_has_removed_products == true %}
        Sorry, some Products in your Cart have been removed because they are no longer for sale.
    {% endif %}
</p>

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. {% session cart_has_removed_products = null %}

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:

s_e_cart_inventory_check({checkout_url: '/checkout'
                                        item_cb: my_function_name
                                        success_cb: undefined });

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

 <input>: 
 <p class="s-e-cart-inventory-warning">
     Sorry we can't supply this many items of ${name}- only ${inventory} in stock.
 </p>

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:

<script>

  document.addEventListener('DOMContentLoaded', function() { s_e_cart_inventory_check({}) });

</script>

On Change

Example To be added to the item.liquid file:

<input type="number" 
       id="quantity" 
       name="quantity" 
       min="1" 
       max="{{this.inventory.quantity | default: 1}}" 
       value="{{this.cart_data.quantity}}" 
       onchange="
s_e_cart_update_quantity(event.target.value,{{this.cart_data.cart_id}}
'{{context.authenticity_token}}'
{confirm_immeditately: true
check_inventory_after: true });
">

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:

<button class="btn btn-success" 
        onclick="s_e_cart_inventory_check({checkout_url: '/checkout'})">
        Confirm and Checkout
        </button>

Manage and edit custom fields that have been added to your Products.

Adding Custom Fields To Your Module

Whilst editing the Products Module Structure, you can add custom fields to add to items.

You can use a variety of field types when creating custom fields, such as:

• Text (String) - Single line text field, used for short text inputs.

• Text (Multiline) - Multiline text field, used for longer text inputs.

• Checkbox - Comma seperated e.g. Checkbox 1, Checkbox 2

• Radio Button - Comma seperated e.g. Radio 1, Radio 2

• Dropdown (Single Item) - Comma seperated e.g. Option 1, Option 2

• Dropdown (Multi Item) - Comma seperated e.g. Option 1, Option 2

• Datasource (Single Item) - Access data of an item from a selected WebApp or - Module. Output within Detail, List or Form layouts.

• Datasource (Multi Item) - Access data of multiple items from a selected WebApp - or Module. Output within Detail, List or Form layouts.

• Image (Single) - Choose an image from File Manager

• Image (Array) - Choose multiple images from File Manager

• File - Media upload field

• Folder - Choose a folder from File Manager

• Date - Select a date

• Number (Integer) - Choose between a minimum and maximum integer for each item

• Number (Float) - Choose between a minimum and maximum float for each item

• Boolean - Toggle 'Yes' and 'No'

• Custom Array - Comma seperated e.g. Option 1, Option 2

Editing Custom Fields On Items

Whilst editing a Product, head to the "Custom Fields" tab.

Here, you can edit the custom fields added to the Module, for each item.

For example, here, there is a custom field added called "test" with the type of File. An image, video, or file can be added here to this item.

The Standard Fields tab is where you can create and edit key information of a Product including: Name, Slug, Release and Expiry Date, and Product Content. You can also enable or disable this Product, and add in an image and a description.

Where can you find 'Standard Fields'?

From your list of Products, click the name or the pencil icon to the right-hand side of an existing Product to view the 'Standard Fields' tab.

Standard Fields Overview:

Here, you can manage and edit key information about your Product, such as:

• ID - This is the Product’s unique ID in your site’s database. It is generated automatically when you first save a Product.

• External ID - This is a unique ID which is helpful when importing and exporting data. It is generated automatically when you first save a Product. Item Name - The name of your product

• Item Slug - This will display at the end of the URL for the Product detail page. (To change the preceding slug, go to eCommerce / Settings in the left-hand menu.)

• Weighting - Controls where your product appears in a list view if it is sorted by weighting.

• Release Date - The date your Product will become visible on the site. This can be used to plan a Product Launch.

• Expiry Date - The date your Product will be discontinued on the site. It is possible to change this after expiry.

• Enabled - If toggled to false, the product will be hidden from the site. This is useful if, for example, a Product has been temporarily recalled.

• Description - A description of your Product.

• Image - It is possible to add further images as custom fields. See custom field sets.

• Product Code (SKU) - This is the product code you use within your business (usually on barcodes) to identify this product.

• View Item Use the "View" button at the bottom of this area to view this item on the front-end.

Prerequisites

For existing Sites, make sure you have updated to the latest version of the eCommerce Module in Portal. For new Sites, you'll need to install the eCommerce Module.

Create some eCommerce Products Set up Product Detail Pages and a Shopping Cart. Try the How to Set Up a Shopping Cart and Guest Checkout Tutorial to learn more about setting this up. To learn more about customising the layouts, visit the following for Product Detail Layouts, Cart Layouts, Liquid reference.

Introduction

Some companies prefer to give Quotes and generate Leads rather than asking Customers to pay for Products immediately as they order.

A customer generates a quote by:

• Adding Products to their Cart

• Submitting a Quote Only form

A Client will see the following:

• User Submissions are saved in the CRM.

• In the CRM the User will have an order with the status: "Quote Only". This will contain all the Products that were in their Cart when they submitted the Form.

You can develop this further with:

• Custom Fields and Custom Field Sets allow you to add additional fields to the Form.

• Fully-customisable Layouts would allow you to style the - Product Detail Page and Cart differently e.g. hiding Prices, should your project require it.

#Tutorial

Step 1: Create a Form

In the Payments Tab, toggle on "Use as a payment form" and select "Quote Only" from the dropdown.

Step 2 - Use Toolbox to insert this Form on a Page

First, create your Page or select a Page you've created earlier.

Next, in the Page Builder tab, use Toolbox on the right-hand side to enter the Form. You can find it under eCommerce/Insert Quote Form.

The code should look something like this:

{%- include 'ecommerce/quote', form_id: '17', layout: 'default' -%}

... where the form_id matches your Form's ID.

Step 4 - ...and you're set up. Time to try it out!

Add items to your Cart

Navigate to your Page and Submit the Form

Inspect the Order in Admin

Any Orders produced in this process will have the status: "Quote Provided" in Admin. You can click on any email in the "User Email" column to find the CRM entry for the User who submitted this Order.

Note - Generating a Quote in this way will not remove stock from Products' Inventories. However, Products cannot be added to the Basket if they are out of stock.

Customising Layouts

With customisation, you can make further changes to the Layouts including hiding prices from Product Detail Page and Cart.

For the default Layout, the following Liquid will be taken care of for you, but when building a custom Layout you must make sure it is still included on the line before the submit button:

{%- include 'ecommerce/quote_only' -%}

In the Examples above we started with a Starter Site and copied the code from the default Form Layout into a new Layout, editing the appearance of the Button.

Adding a Product is very similar to adding a WebApp item, but with additional features which are fully integrated into other features of Siteglide eCommerce e.g. Shopping Cart, Checkout and Orders.

Creating A Product

Firstly, navigate to your Products.

On the right-hand side above your list of Products, you'll see a blue button that says 'Add New Product', click this and you'll be on your way to creating a new Product.

This will redirect you to 'Standard Fields' page.

Once you have filled out these fields, click 'Save'. Your new Product will then show in your list of Products.

Edit A Product

Whilst viewing your list of Products, click on the Product name, or the pencil icon to the right-hand side of any existing Product to take you to the Standard Fields page.

Once you are happy with your edits, click 'Save'.

Securing Products

Whilst editing your Products Module Structure, you can choose to secure items within this Module.

• Show in list - show these items in the list view and hiding the detail view behind a 401 page

• Hide - hide these items in the list view and hiding the detail view behind a 404 page.

Securing Individual Items

Whilst editing a Product, head to the "Secure Zones" tab.

Here, you can add an existing Secure Zone to this item; if you have no Secure Zones to choose from, you can find out how to create one here.

Once you have added Secure Zones, make sure to click save.

Custom Field Sets are groups of Custom Fields that you can reuse across a range of Siteglide Records including Users, and Products. Head to Site Manager > Custom Field Sets in the left-hand side Menu, to start using.

Where can you add Custom Field Sets to your Products?

Once your Custom Field Set has been created, you can assign it to an individual Product. From Standard Fields, navigate to the Custom Field Sets tab. Choose a Custom Field Set that you have created in the drop-down and click Save.

Any Custom Field Sets you have added within the Product will appear as tabs within Custom Field Sets.

You can press the "+" icon at the end of the row to add a new Custom Field Set to this Product. The fields you added previously can now be filled in with Product-specific information.

Set your inventory levels so that Clients can see if stock is running low, and customers cannot purchase an item that is out of stock.

From your Standard Fields tab within a Product, navigate to 'Inventory Control'.

Here, you can set your current stock levels.

Inventory Type :

• Global - Applies to the Product Attribute - Inventory is controlled against each individual Attribute Option

• None - No inventory control needed

If the chosen type is 'Global', then the following 2 options will show in this same tab:

• Display Type (when zero inventory) - This can be controlled on a per-Product basis. Use it to control what happens when a Product is out of stock; you can either hide the product from the shop or display it without accepting orders.

• Quantity - Set the quantity you currently have in stock.

Adding your Products to Categories enables visitors to easily navigate and search by Category, and also to output a specific Category.

How do you add a Product to a Category?

From your Standard Fields, navigate to the 'Categories' tab.

Within this tab, you see a list of your Categories.

To assign a Product to a Category, click the checkbox next to the Category that you'd like to assign it to and click save.

From here, you can also click 'Manage Categories' to add new Categories and edit the settings. For more information about Categories, click here.

SEO stands for Search Engine Optimisation and is used to help boost your ranking in search results. SEO is incredibly important in attracting new visitors to your site, you'll show higher up in search engines enabling more people to find your site.

Where Can You Find SEO Settings For Your Products?

When viewing Standard Fields, navigate to the SEO tab.

Editing Your Product's Metadata

Within your SEO settings:-

• Page Title - Label your Product so that visitors know what it is

• Meta Description - Describe your Product so that visitors know what it is about. (When typing in the description field, it will show you a countdown of advised character length.)

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.

<label for="quantity">Quantity</label>
<input type="number" id="quantity" name="quantity" value="{{this.cart_data.quantity}}">

Like so:

<label for="quantity">Quantity</label>
<input type="number" id="quantity" name="quantity" value="{{this.cart_data.quantity}}" 
onchange="s_e_cart_update_quantity(event.target.value,{{this.cart_data.cart_id}}
'{{context.authenticity_token}}', false);">

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.

s_e_cart_update_quantity(event.target.value, {{this.cart_data.cart_id}}
'{{context.authenticity_token}}', false);

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.

<button class="btn btn-primary" 
        onclick="s_e_cart_update(false,'{{context.authenticity_token}}')">Update cart</button>

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.

s_e_cart_update(false,  '{{context.authenticity_token}}', false, function(reload, check_inventory_after) {
 //Do something after cart update
} );

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.

<p><strong>TOTAL PRICE:</strong> 
    <span data-s-e-live-cart-total>
    {% include 'ecommerce/price_total'
                format_type: 'formatted' -%}</span></p>

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.

<td>{{this.price.currency_symbol}}
        <span data-s-e-live-cart-item-price="{{this.cart_data.cart_id}}">
            {{this.cart_data.price}}
            </span>
            </td>

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.

Pre-Requisites

• You have read

• You have Installed the eCommerce Module

• You have installed the Secure Zones Module

Introduction

Siteglide eCommerce is even more powerful with Secure Zones. With the security of a Secure Zone, you can show your Users more sensitive data about their shopping experience.

Step 1) Create a Secure Zone

Create a Secure Zone which will used by shoppers on your eCommerce site.

Alternatively, you can use a Secure Zone that you have created already.

Find out more about the Secure Zones Module here:

Step 2) Create a "My Orders" Page in a Secure Zone

Create a new page which will display a list of Products Users have ordered.

In CMS / Pages, open the Page you have chosen and open the Details tab. Click the Secure Zones accordion to reveal the "Select a Secure Zone" field.

Click in this to open a drop-down list of your Secure Zones and select the one you wish to be accessed by Users after they complete Checkout.

Step 3) Set the Checkout Form Redirect to your Orders Page

Make sure your Checkout Form is still in "Test Mode" unless the Site is Live.

Find Forms in the Siteglide Admin’s left-hand side menu under CMS / Forms. Select your checkout Form in the list:

Next, click the "View Form" button to edit:

Step 4) Add the Secure Zone to the Checkout Form

Select the Secure Zones tag and then click in the Secure Zones Input field to see a dropdown of Secure Zones you have already created.

Select the Secure Zone you want to log your Users in to when they complete the form.

Press the "Save" Button to save your changes. At this point:

Completing the Checkout Form will log Users in to the Secure Zone It will also redirect the Users to the My Orders Page The Users will be allowed to access the My Orders Page, because they are logged into the Secure Zone. Other Users who are not logged in will be unable to access the My Orders Page.

Step 5) Create an Orders List Layout

As Orders List Layouts are for showing secure information about Users, they are stored under the following file structure:

module_5/user_orders/name_of_my_layout.liquid

Create a new file in the user_orders folder and give it a name of your choice. Make a note of the name you gave it.

Step 6) Add Orders layout to the Orders Page

Add the following liquid to your Orders page to output a list of the current logged-in User’s Orders:

{%- include 'user_orders', layout: 'name_of_my_layout', sort_type: 'id', sort_order: 'asc', show_pagination: 'false' %}

The layout parameter should take the name of the list layout you created.

Step 7) Develop your Layout

Your layout will have access to the "orders" object. You can loop over each order in the "Order" object with the following liquid (the "order" variable can be renamed to anything you like). For example:

{% for order in orders %}
  <!-- {{order.id}} etc. -->
{% endfor %}

See the orders reference for available fields:

Next Steps

You could add a Secure Zone to other pages related to your eCommerce flow, for example the Cart, in the same way you did with the Orders page. You could redirect the users to a login page when they visit the Cart page and are not logged in.

Learn more about Secure Zones here.

Wondering how to adjust the Product Detail Page based on Category?

Answer:

As a User navigates to your Product Detail Page, Siteglide will load the Detail View you have specified in your eCommerce Settings. However, it is perfectly possible to customise this based on , using Liquid logic! You can read more about using Categories on the Layout of the WebApp or Module Item they belong to .

In this example, you'd need to know the ID of a category you want to display; this can be found in Admin when you select a category. E.g. let's say we want to display something special when something has the category "Featured" and you know it has an ID of "111111":

{% assign featured_id = "111111" %}
{% for category_id in this.category_array -%}
  {% if category_id == featured_id %}
    <!-- Add Featured Content Here -->
  {% endif %}
{% endfor %}

Attributes allow you to specify aspects of the Product that the customer can customize as they order. This can change the price and enable customers to choose a variation of this product: for example, to have this in a different colour.

Where can you do this?

From your Standard Fields in a Product item, navigate to the Attributes tab.

Click the "Add Attribute" button to add a new Attribute. This will appear as a new tab within this area. This can be deleted by clicking "-" next to the name of the Attribute.

• Name - This is the name of the Attribute which can vary on this product e.g. "Size" or "Colour". Toggling "Enabled" off will hide this Attribute from view while customers are making Orders.

• Image - Choose an image for this Attribute

• Add Attribute Option - Clicking this will open a table for the different Attribute Options e.g. if you named your Attribute "Colour", you may choose options of "Red" and "Green".

Press the "Add Attribute Option +" button to add a new row to the Options table. Then fill in the fields below:

• Name - Add the name of the option e.g. "Large" or "Green"

• Product Code (SKU) - This is the internal Product Code you use in your business for Products with this Attribute Option

• Enabled - Unlike the previous enabled toggle, this doesn't affect the whole attribute, but only this particular option

• Chargeable Price - This field increases the total Price of the product when this Attribute option is selected e.g. a product costs $10 but a "metallic silver" version costs $2 extra, you would add the value 2 here. A price of 0 would mean that the Attribute does not add to the total Price when selected

• Display-only Price - Select a price that you'd like to display only

• Inventory Available - If the Product's Inventory Type is 'Attribute' then you can set how many of this Attribute Option are available here

• Image - Select an image for this Attribute Option

• Delete - Deletes this Attribute Option

Add Pricing to your Products to enable visitors to easily see costs involved with items on your Site.

Where can I find Pricing?

From your Standard Fields tab of a Product, navigate to the Pricing tab.

Here, you can set and change the price for the Product.

You can set and edit fields for Pricing, such as:

• Currency - Currently only one Currency is supported at a time.

Find a full list of supported currencies for Stripe, Paypal, and Authorize.net. Alternatively, you can build your own payment gateway integrations, find out more here.See eCommerce Settings to set your currency.

• Chargeable Price - This is the main price that will be added to the total the Customer pays when the Product is added to a basket. It can be modified using Product Attributes.

• Display Only Price - Use this to display an extra price such as RRP or Price Before Tax.

Manage and edit your Products to enable detail views, secure this module, and add custom fields.

Edit Module Structure

Above your list of Products, you have the option to "Edit Module Structure".

Here, you can manage and edit information about this Module, such as:

• Has detail view? - Choose whether this Module will have a detail view

• Slug - Create a slug for this module

• Detail Page Template - Choose a page template for this Module to use when in detail view

• Detail Layout - Choose a detail layout for this Module to use

• Secure Zones - Items can be made secure - Choose to secure these items, and whether to show these in list or hide.

• Standard Fields - These are the same fields that can be seen in the Standard Fields tab when editing

• Custom Fields - Here you can add, edit and remove custom fields to use for your Module

How to customise the Shopping Cart Layout

Prerequisites

• You have completed

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:

` | | Shipping Price Before Tax | `` | | Shipping Price Tax Amount | `` | | Total Item Price | `` | | Total Item Price Before Tax | `` | | Total Item Tax Amount | `` | | Total Price Reduction (due to Discounts) | `` | | Final Total Price Before Tax | `` | | Final Total Tax Amount | `

| | Final Total Price | \{% include 'ecommerce/price_total', format_type: 'formatted' -%} |

` |

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.

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:

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}}')"
/>

Use Workflow and Autoresponder Emails to send confirmation messages to customers, including a detailed breakdown of their Order.

Prerequisites

• You have installed eCommerce Module v0.12.0 or later. Checkout to find out how you can install the latest version.

• You have set up a Checkout or Quote-only Form. Learn more about Checkout here: or learn more about the Quote-only feature here:

Introduction

You can now add details of a customer's eCommerce Order to Workflow and Autoresponder transactional emails. Give your Client and the customer peace of mind, as well as valuable records for their safekeeping.

eCommerce Orders are created by Checkout and Quote-only Forms.

Within the email, you can also access any fields that were submitted along with the original Form. Learn more here:

Syntax

Add the following Liquid tag to include the details of the customer's most recent Order:

{% include 'ecommerce/order_details', layout: 'email' %}

In an email notification, this will always be based on the Form that triggered the email. Only an Order generated by that Form submission will be visible in this context. This means that Autoresponder emails will always show Form Submission data from the correct User.

Layouts

File Structure

You can use an existing Layout, or create a new one in this File Structure: layouts/modules/module_14/order/my_layout/ Within your Layout folder, you'll need:

• An item.liquid and a wrapper.liquid file

Developing the Layout

Inside your order_details layout you'll find an item.liquid and wrapper.liquid file.

Wrapper

You can use the wrapper.liquid file to build the main HTML structure of your Layout. When you're ready to include the Order Details, use the following Liquid to include the item.liquid file:

{%- include 'modules/siteglide_ecommerce/ecommerce/get/get_order_details'
    item_layout: 'item' 
-%}

Item

The item.liquid file will have access to the This object, which will contain details about the Order:{{this}}

Orders involve several different types of models and can be complex. When developing you will need to use loops to take into account each different eCommerce element which may be a part of the Order.

When developing a custom layout, it may be helpful to refer to the default Layout.

Looping over Products This loop will find any Products in the Order and loop over them.

{%- for product in this.order_products -%}
    <!-- Output {{product}} -->
{% endfor %}

Looping over Products and accessing Fields Within a Product Loop, you can access the fields associated with that Product.

• {{ product.product_name }}

• {{ product.quantity }}

• {{ product.product_code }}

• {{ product.currency_symbol }}

• {{ product.price }}

Looping over Products, then looping over Attributes

{%- for product in this.order_products -%}
    <!-- Output {{product}} -->
    {% for attribute in product.order_product_attributes -%}
         <!-- Output {{attribute }} -->
    {% endfor %}
{% endfor %}

Outputting Shipping Method The following fields are available relating to the Shipping Method:

• this['Shipping Method Name']

• this['Currency Symbol']

• this['Shipping Method Price']

• {%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter', price_data: this['Shipping Method Price'] -%} - a formatted Shipping Price

Example of only including Shipping Information if it was set:

{% if this['Shipping Method Name'] != blank %}
     {{this['Shipping Method Name']}}
     {{ this['Currency Symbol'] }}
     {%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter'   
                 price_data: this['Shipping Method Price'] -%}
{% endif %}

Outputting Totals

• {{ this['Currency Symbol'] }}

• this['Total Price']

• {%- include 'modules/siteglide_ecommerce/ecommerce/price_formatter', price_data: this['Total Price'] -%} - A formatted total price

Orders Detail Layout

Within the Orders Detail Layout you will have access to the orders array variable. To display a list of items in the single order, you should add a Liquid loop like this:

{% for order in orders %}
  <!-- {{order.id}} etc. -->
{% endfor %}

Within the loop, you can use properties of the object within the loop iteration as detailed in the table:

Offer your customers better prices when they purchase in bulk. This feature lets you define as many levels of Volume Pricing as you like.

Introduction

Volume Pricing allows your Client to offer better prices to customers who buy products in greater quantities.

Let's say for example a product normally costs £5, but to encourage larger sales , the following table of prices are available:

If the customer orders 105 items, they will have passed the quantity threshold of 100, so will have access to the price of £4 per product for all 105 items. They did not order a high enough quantity to get the best available price.

Attributes

At the present, when two alternate versions of the same Product with different attributes are present in the Cart, both their quantities will be added up and counted towards the Volume Pricing Calculation.

Setting up Volume Pricing

There is no need to implement any front-end code in order to start using Volume Pricing. All you need to do is define the pricing in the Admin against individual products and those prices will become available.

Outputting Volume Price Information in Product Layouts

You may wish Front End to dynamically display the available prices for a product. To do so, you can loop over each pricing threshold and display the prices in a table, list or format of your choice.

Inside the Product List/ Detail Page item.liquid file, you'll have access to the following fields:

When looping over an object like this['Volume Pricing'], .first allows you to access the key (here the quantity threshold) and .last allows you to access the value (here the price).

First though, we use logic in the first line to check if the pricing has been enabled:

{% if this.['Volume Pricing Enabled'] == true %}
  <h3>Volume Pricing Options Available</h3>
  <ul>
    {% for volume_price in this['Volume Pricing'] %}
      <li>Purchase more than {{volume_price.first}} and pay only {{this.price.currency_symbol}}
        {% include 'modules/siteglide_ecommerce/ecommerce/price_formatter'
                    price_data: volume_price.last 
        -%}</li>
    {% endfor %}
  </ul>
{% endif %}

Accessing Volume Prices in the Order Confirmation Email

Inside the Order Confirmation Email, you'll have access to the following relevant fields.

The following example shows how the Volume Pricing can be shown inside a <td> element in an Order Confirmation Email.

<td style="padding: 5px 5px 5px 15px; font-weight: 200;" align="right">
  
{% if product.volume_pricing_threshold_reached != blank %}
    <span style="color: red; text-decoration: line-through;">
      {{ product.currency_symbol }}{{product.volume_pricing_original_price}}</span>
    {{ product.currency_symbol }}{{product.price}}
  {% else %}
    {{ product.currency_symbol }}{{ product.price }}
  {% endif %}
</td>

See the Order Confirmation Email documentation for more.

Help customers find regular purchases and favourite products with the reorder button.

Introduction

Help customers find regular purchases and favourite products with the reorder button. The button can be added to a user_orders Layout or any other Layout where you have access to an Order ID.

For this reorder feature to work, the User:

• Must be logged in

• Must have been logged in when they originally made the Order

The feature fetches all Products from that Order and adds those that are still available to the Cart. This gives the User a chance to review and adjust quantities before Checkout.

A message can also be displayed to the User to detail any Products from that previous Order which are no longer available. Though, this is only possible where an Order still exists in the database and has not been deleted.

Developing the Order Button

Including the Button

The following Liquid will output the reorder button:

{% include 'ecommerce/reorder_button', layout: 'default', order_id: this.id %}

Parameters:

• layout

• order_id

The button can be added in any Liquid Layout, but you'll need to have access to the ID for an Order belonging to that User- which is most easily available in the User Orders Layout or the Order Details Layout (note that a User can't be logged in when reading an email, so this feature will not work from an Order Details Layout in an email).

In the User Orders Layout, the exact Liquid for the ID will depend on the variable you've set in the loop. In the following example, the variable assigned to each iteration of the loop is this. so the Order ID is available inside the loop as this.id.

{% for this in orders %}

  {% include 'ecommerce/reorder_button'
     layout: 'default'
     order_id: this.id 
  %}

{% endfor %}

The button will only work if the User is logged in, so you may wish to add the following logic to an Order Details Layout to make sure the User is logged in before displaying:

{% if context.current_user.id %}
<!-- Code only runs if User is logged in -->
{% endif %}

The Button Layout

Adding the button will load a small button layout. You can find the default Layout or create a custom Layout at the following path: layouts/modules/module_14/components/reorder_button/my_layout_name.liquid

Adding the function The styling of the button is completely up to you. To carry out its main functionality, the button requires an event to be attached to it which will run a JavaScript function:

onclick="s_e_reorder({ order_id: '{{order_id}}'
                        token: '{{token}}'
                        cart_url: '/cart'
                        error_cb: error
                        success_cb: success})"

The function takes a single argument containing an options object. The available arguments are as follows:

Adding a Custom Error Function The Custom Error function will be called in the following circumstances (the table also shows the value of the "error" parameter passed back when this occurs):