Basics​

Learn about Handlebars basics and apply them in theme development alongside Handlebars objects and Handlebars helpers.

Resource handles​

Resource handles are unique identifiers that distinguish different resources in a store. Resource handles are used to construct resource URLs or to retrieve information about corresponding objects. Common resource objects that have handles include product, collection, article, and blog. Other resource objects, such as link and linklist, also have handles.

Each resource for the same object has its unique handle. Take the product object for example, if a store has two different products, their resource handles are distinct.

Create handles​

By default, handles are automatically generated based on the resource title or name specified in the SHOPLINE Admin. As shown in the following figure, the product titled 23summer new has the automatically generated handle 23summer-new.

Handles are automatically generated according to the following rules:

• Handles for alphabetic characters are always in lowercase.
• Spaces and special characters are automatically replaced with hyphens (-).
• Multiple consecutive spaces or special characters are replaced with a single hyphen.
• Leading spaces or special characters are removed.
• Handles within the same resource are unique. If titles or names in the same resource are duplicated, handles are automatically marked with incrementing numbers. For example, if two products have the same title bed, their handles would be bed and bed-1 respectively.

You can edit the handle directly in the Search engine optimization section on the resource editing page when adding a resource. For example, as shown in the following figure, when adding a product named Shirt, you can manually change its handle from the default shirt to shirt1.

Modify handles​

Once a resource is added, changing its title will not update the handle.
To modify the resource handle, you need to go to the specific resource page in the SHOPLINE Admin, find the Search engine optimization section, and modify the handle there. If you have referenced the resource using its handle, ensure to update these references when modifying the handle.

Reference handles​

All objects with handles have a handle property. For example, you can output a product's handle using product.handle. You can also reference an object within a parent object using its handle in two ways:

• Dot notation **.**: Use a dot to directly connect the parent object with the handle, for example, linklists.header.
• Square bracket notation **.[ ]**: Enclose the handle string in brackets. For example, linklists.['header']. Variables inside the bracket are not supported.

Operators​

Handlebars supports basic logical and comparison operators, which can be used with the if and unless helpers.

<!-- Render 'The flower is on sale!' if both conditions are met:
     1 The product.compare_at_price value is greater than the product.price value.
     2 The product type is 'Flower'.
     Otherwise, render 'The product title is not a flower or the product is not on sale.'.
     -->
{{#if product.compare_at_price > product.price and product.title == 'Flower' }}
    The flower is on sale!
{{else}}
    The product title is not a flower or the product is not on sale. 
{{/if}}

Operator precedence​

When multiple operators are used within a helper, Handlebars processes them from right to left.

<!-- Render 'true'
     true and (false or (false or true))
     true and (false or true)
     true and true
     true
     -->
{{#if true and false or false or true}}
true
{{else}}
false
{{/if}}

true

You can use () to change the evaluation order. The system first executes the helper expression within (), and then proceeds with the remaining operations.

<!-- Render 'true' because Handlebars evaluates expressions from left to right like this:
     true and (( true and true ) or false)
     true and (true or false)
     true and true
     true
     -->
{{#if true and (if true and true) or false}}
true
{{/if}}

true

Data types​

Handlebars outputs the following data types.

string​

A series of characters that are enclosed in single or double quotes.

number​

Numeric value, including floats and integers.

boolean​

Binary values, either true or false.

null​

An undefined value.
The helpers or outputs that return null print nothing on the page. They are also considered as false.

array​

A list of variables of any type.
To access all items in an array, use the for helper to iterate over each item in the array.
To access a specific item in an array, use the notation .[]. An array index starts at 0.

Truthy and falsy​

All data types must return either true or false. Those that return true by default are called truthy, and those that return false by default are called falsy.
Handlebars may treat unexpected values as truthy. Refer to the following table for common values that are considered to be truthy or falsy.

Table 2. Examples of common truthy and falsy values

Example​

When checking values in Handlebars, be cautious that a value may not be in the format you expect, but it can still be regarded as truthy. For example, in the following sample, if the setting.product object is empty, Valid value. is rendered, because Handlebars treates an empty object as truthy.

{{#if settings.product}}
Valid value.
{{else}}
No value for this setting has been selected.
{{/if}}

Whitespace control​

You can strip the whitespaces from the output in Handlebars by adding a ~ character next to the curly braces. This tells Handlebars to automatically remove all whitespaces adjacent to the ~ symbol when parsing the template, until it encounters a non-whitespace character or another Handlebars expression.

start
{{~ settings.product.title ~}}
end

startend