---
title: "Basics"
doc_type: static
doc_category: static
doc_version: v20270301
source_url:
html: 'https://developer.shopline.com/docs/handlebars/basics'
md: 'https://developer.shopline.com/docs/handlebars/basics.md'
---
# Basics
Learn about Handlebars basics and apply them in theme development alongside Handlebars [objects](https://developer.shopline.com/docs/handlebars/objects/additional-checkout-buttons.md) and Handlebars [helpers](https://developer.shopline.com/docs/handlebars/helpers/syntax/comment.md).
## 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`](https://developer.shopline.com/docs/handlebars/objects/product.md?lang=en), [`collection`](https://developer.shopline.com/docs/handlebars/objects/collection.md), [`article`](https://developer.shopline.com/docs/handlebars/objects/article.md), and [`blog`](https://developer.shopline.com/docs/handlebars/objects/blog.md). Other resource objects, such as [`link`](https://developer.shopline.com/docs/handlebars/objects/link.md) and [`linklist`](https://developer.shopline.com/docs/handlebars/objects/linklist.md), 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](https://admin.myshopline.com). As shown in the following figure, the product titled `23summer new` has the automatically generated handle `23summer-new`.
Figure 1. An example of a product collection title and handle
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`.
Figure 2. An example of editing a handle
### 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.
> **Note**
>
> For the `link` object, handles of `main-menu` and `footer` are automatically generated based on link titles and cannot be modified.
### 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.
| **Operator** | **Description** |
| --- | --- |
| `==` | equal to |
| `!=` | not equal to |
| `>` | greater than |
| `<` | less than |
| `>=` | greater than or equal to |
| `<=` | less than or equal to |
| `and` | condition A and condition B |
| `or` | condition A or condition B |
| `contains` | check if a string exists within another string or an array |
Table 1. Supported operators for Handlebars
```shell
{{#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.
```shell
{{#if true and false or false or true}}
true
{{else}}
false
{{/if}}
```
```shell
true
```
You can use `()` to change the evaluation order. The system first executes the helper expression within `()`, and then proceeds with the remaining operations.
```shell
{{#if true and (if true and true) or false}}
true
{{/if}}
```
```shell
true
```
## Data types
Handlebars outputs the following data types.
### string
A series of characters that are enclosed in single or double quotes.
> **tip**
>
> You can use `''` or `""` to check if a string is empty.
### 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`](https://developer.shopline.com/docs/handlebars/helpers/iteration/for.md) 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`.
> **note**
>
> You cannot initialize an array directly with Handlebars. However, you can use the [`split`](https://developer.shopline.com/docs/handlebars/helpers/string/split.md) helper to convert a comma-separated string into an array.
## 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.
| **Value** | **Truthy** | **Falsy** |
| --- | --- | --- |
| true | ✔️ | |
| false | | ✔️ |
| null | | ✔️ |
| string | ✔️ |
|
| empty string | | ✔️ |
| 0 | | ✔️ |
| integer | ✔️ | |
| float | ✔️ | |
| array | ✔️ | |
| empty array | ✔️ | |
| page | ✔️ | |
| object | ✔️ | |
| empty object | ✔️ | |
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.
```shell
{{#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.
```shell
start
{{~ settings.product.title ~}}
end
```
```shell
startend
```