Contributors:

shipping_options

This component renders a form select element of all shipping options configured on the site, and can also be used to output shipping option data to a Liquid collection.

When used in the Shopping Cart, it will also be responsible for rendering the correct shipping option/s based on the cart conditions and shipping option rules.

{% component type: "shipping_options" %}

Parameters and Options

type

shipping_options

This is the name of the entity that needs to be used for the component retrieving function.

layout

<path/to/layout>

Path to file that will contain the Liquid layout content to be parsed.

If an empty string, nothing will be rendered.
If paramater is not included, the default virtual layout will be rendered (see below).

filteredCountry

<COUNTRY CODE>

Returns only those options available for the defined country (by country code, ie: US, CA, AU, NZ, etc.) - since these items can belong to, or be restricted to, a specific country.

The default shopping cart setup will use the default domain country unless a country has been selected from the shipping country dropdown on the shopping cart page.

collectionVariable

<yourLiquidVariableName>

Assigns the data to a Liquid collection enabling further access to the data on the Page or Template using Liquid.

Your collectionVariable value must only contain English letters, numbers or underscores. Spaces or special characters are not supported.

Liquid Output

The below output shows the sample list of shipping options configured for the site:

{
  "Items": [
    {
      "Name": "Local Delivery",
      "Price": 10.0000,
      "TaxPercent": 0.0,
      "TaxPrice": 0.0000,
      "TotalPrice": 10.0000,
      "Id": "3543",
      "CountryCurrency": {
        "CurrencyCode": "USD",
        "CurrencyName": "US Dollar",
        "CountryDisplayName": "UNITED STATES",
        "CountryCode": "US"
      }
    },
    {
      "Name": "Pick-up in Store",
      "Price": 0.0000,
      "TaxPercent": 0.0,
      "TaxPrice": 0.0000,
      "TotalPrice": 0.0000,
      "Id": "3544",
      "CountryCurrency": {
        "CurrencyCode": "USD",
        "CurrencyName": "US Dollar",
        "CountryDisplayName": "UNITED STATES",
        "CountryCode": "US"
      }
    }
  ],
  "Params": {
    "type": "shipping_options",
    "layout": "",
    "collectionvariable": "shippingCollection"
  }
}

Virtual Layout

If not using any custom layout or collection, the default virtual layout will output as a form select element:

<div class="cms_fake_select">
    <select data-cms_cart_shipping_options="" data-cms_cart_shipping_option_name_layout="{itemName} ({itemPrice})">
        <option value="">Please select</option>
        {% for item in this.items %}
        <option value="{{item.Id}}" {% if  shoppingCartData.shippingOption.shippingOptionId == item.id %} selected="true" {% endif %}>{{item.Name}} ({{item.Price  | domain_money_format }})</option>
        {% endfor %}
    </select>
</div>

Rendering the form element:

This layout does impose some limitations with customisation and basically there are 2 main parts you can modify:

the <select> element and any wrapper you might add/remove from around it.
the visible text and price of the <options> element, but only via the placeholders provided, which are: {itemName} and {itemPrice}

The data attribute on the <select> element allows you to define the Name/Price format used in the <option> text:

data-cms_cart_shipping_option_name_layout="{itemName} ({itemPrice})"

You can omit either or both {itemName} and {itemPrice} from the data attribute if required. However, the rest of the HTML layout will be restored to default via the eCommerce Javascript.

To customise this layout you’ll need to make your own custom layout file and reference that in the shipping_options component tag, like so:

{% component type: "shipping_options", layout: "/PATH-TO/YOUR-CUSTOM-LAYOUT.layout" %}

It’s recommended that you use a copy of the Virtual Layout above and simply change the placeholders as required.

Accessing the Data

JSON Output

You can output the full JSON for your component data by referencing the root Liquid object {{this}} in your module’s layouts, or directly on your page, if using the collectionVariable parameter in your component tag.

For example:

{% component type: ... collectionVariable: "myData" %}

You can then render the JSON like so:

{{myData}}

For more details on using this approach, see Part 2 of the free ‘Learning Liquid Course’.

Rendering Property Values

This data is also accessible directly on the Page or Template via a Liquid Collection by adding collectionVariable to the Component.

An example using collectionVariable with value "shippingCollection":

{% component type: "shipping_options", collectionVariable: "shippingCollection" %}

Accessing a specific item within the collection. In this case the second item (zero based index), which in our example would render the value Pick-up in Store

{{shippingCollection.items[1]['name']}}