Liquid Templates are used in several places in B2B Marketplace. They allow for flexible configuration of custom layouts using Liquid.net, without requiring compiled code changes.

Overview

Liquid is an open source templating language that was originally created by Shopify that we have opted to use within our product. If you are not familiar with liquid, there are a couple sections from Shopify’s help documentation that we recommend reading through to get started.

Our web site is using ported version of liquid for the .net framework called DotLiquid. Additional documentation on DotLiquid can be found on their wiki.

http://dotliquidmarkup.org

Creating a New Template

All liquid templates for Customer Portal are currently stored under: /assets/liquid/Templates

To create a new liquid template, use the text editor of your choice to create a new file and ensure it’s saved with a .liquid file extension. Ex. custom.liquid. If the liquid template your creating is potentially going to be embedded in other templates using a liquid include, then the file name would need to start with and underscore. Ex. _custom.liquid.

Each liquid template can have an accompanying .json file to set up any template properties you would like to be able to reference, both from within the template and the Manager Add-On in Business One. The file should be named the same as the template it’s meant to pair with .liquid.json as the file extension. For example:

  • Template File: Product-details.liquid
  • JSON Settings File: Product-details.liquid.json

JSON properties

Each JSON settings file must contain the following fields and the appropriate value for each.

Field Name Description
FriendlyName Friendly name for the liquid template.
TemplateContext Specifies where this template is used within the site (ex. Collections).
TemplateFieldMeta Defines the meta data used within this template for each individual property.
FieldName Designer-friendly name of the template property. This is how a property is referenced from within a liquid template
DisplayName Admin-friendly name that appears in the Manager Add-On when configuring the property values in SAP Business One.
Required Defines whether or not the field is required in a template.
DataType Type of data that will be contained within this field. Typically, this is set to text.
ValidValues When data associated with this template must be restricted to specific values, ValidValues can be defined. For instance, if this property is meant to be used to show and hide content on a page, the valid values may be true or false. This can be left blank if it’s not applicable.

A sample of a JSON settings file can be seen below:

{
    "FriendlyName": "Product Details",
    "Template Context": "ProductDetail",
    "TemplateFieldMeta": [
    {
        "FieldName": "show_product_img",
        "DisplayName": "Show Product Image",
        "Required": false,
        "DataType": "Text",
        "ValidValues": [ "true", "false" ]
    },
    {
        "FieldName": "show_QTY",
        "DisplayName": "Show Quantity",
        "Required": false,
        "DataType": "Text",
        "ValidValues": [ "true", "false" ]
    },]
}

Registering a Template in Business One

When a template and its associated *.liquid.json file is added to the website under the assets/liquid/templates, it will automatically get picked up by the addon. This means that it will show up in all the template dropdowns and any additional properties to the addon to update.

Customization Best Practices

To ensure future upgrades go smoothly if you wish to customize and existing template, the best approach would be to create a copy of it to work with instead of just changing the existing file.

In an effort to keep configuration simple and ensure our code is more readable, the out of the box templates have been split up so that there is one main template for each section (collections, products, search, etc.). Code within that template is then split into separate smaller liquid templates that can be inserted in the main template with liquid includes. This helps keep the code readable, and also allows you to potentially reuse it in order templates.

For example, on collections and searches we have two templates to contain the content for list and grid views, and those are set as includes on the main product.liquid and search.liquid templates. We recommend using the same approach when creating your own custom templates to help make maintenance easier on both you and your users.

Data Model

The data model that gets passed to the liquid renderer is fully dynamic and based on several different queries. To get the exact data model for any given template, place the {% debug = true %} on that template and browse to a page that uses that template

Default Liquid Templates

Below is a list of the liquid templates we have included out of the box, and their purpose.

Template Name Purpose
Cart.liquid Display of the shopping cart preview window that can be turned on from within the storefronts config.
Products.liquid Main template that controls the display of collections throughout the site.
_list_view.liquid Used as an include on templates to show items in a list view. Currently used on collections and search.
_tile_view.liquid Used as an include on templates to show items in a grid view. Currently used on collections and search.
_sorting.liquid Used as an include on templates to add sorting functionality. Currently used on collections and search.
_paging.liquid Used as an include on templates to add pagination functionality. Currently used on collections and search.
Search.liquid Main template that controls the display of the search. Currently very similar to the product.liquid template, but does not include sections for a description or banner.
Product-details.liquid Main template for item display.
_varient_grid.liquid Simple version of the grid used to display varients on product details.
_varient_grid_complex.liquid Similar to the _varient_grid.liquid template, but this template includes filtering options. Recommended to display varients on product details where there are a large number of options.
Welcome-screen.liquid Main template for the welcome screen display for B2B users.
_welcome_menu_item.liquid Included on the welcome-screen template to control display of tiled menu items.
Styles.css.liquid Used as a secondary CSS file to contain any references to colors, background images, font types and sizes. They are all set from template properties which enabled users to set them from within the storefronts section of the Manager Add-On.

Liquid Template Properties

This is a list of the existing liquid template properties in use by Customer Portal.

Property Name Description
welcome-screen.liquid  
BannerImage Accepts the path to a banner image that can be displayed on your welcome page.
BannerType Can be set to full or cropped.

Full always shows the full banner image and restricts size based on the screen width. Height can vary to avoid skewing proportions.

Cropped cuts off part of the image as screen size changes, but keeps the image a consistent size.

This property is available in version 93.0 and higher.
PreviewCollection Accepts the name of an existing collection that you wish to display on your welcome screen.
ShowWelcomeMessage Can be true or false.

If true then a white bar containing the welcome message and image (when set) will be displayed. Any value other than true will hide this area.

This property is available in version 93.0 and higher.
_welcome_menu_item.liquid  
HideLinkText Hides the text on the specified link to allow for display of an image including text instead.
BackgroundImage Allows the user to select a background image for the specified link entering the file path.
CardColor Allows the user to select the background color for the specified link.
FontColor Allows the user to choose a font color for the specified link.
products.liquid  
show_product_img Toggles whether to show or hide product images while viewing a collection.
showBanner Toggles whether to show or hide a banner image on a collection.
showDescription Toggles whether to show a description at the top of the page while viewing a collection.
showItemCode Toggles whether to display the item code while viewing a collection.
showAdditionalDetails Toggles whether to display additional details while viewing a collection. NOTE: By default this is only a placeholder. Additional updates to the template must be made in order to configure which UDF’s you’d like displayed here.
show_QTY Toggles whether to display the quantity input field while viewing a collection.
defaultLayout Allows the user to choose whether the list or grid view should be the default displayed on a collection.
showPrice Toggles whether to show price on a collection.
search.liquid  
show_product_img Toggles whether to show or hide product images while using the product search.
showItemCode Toggles whether to display the item code while using the product search.
showAdditionalDetails Toggles whether to display additional details while using the product search. NOTE: By default this is only a placeholder. Additional updates to the template must be made in order to configure which UDF’s you’d like displayed here.
show_QTY Toggles whether to display the quantity input field while using the product search.
defaultLayout Allows the user to choose whether the list or grid view should be the default displayed on the product search.
showPrice Toggles whether to show price on the product search.
product-details.liquid  
show_product_img Toggles whether to show or hide product images while viewing an item.
showAdditionalDetails Toggles whether to display additional details while viewing an item.
show_QTY Toggles whether to display the quantity input field while viewing an item.
show_remarks Toggles whether to display the remarks field from Business One as ‘Notes’ while viewing an item.