# Handlebars basics

Airship uses the [Handlebars](https://handlebarsjs.com/) templating language to support personalization of messaging content.

> **Note:** This is a reference for using Handlebars as implemented in Airship's features, not for the Handlebars project. We do not support all features described in handlebarsjs.com, only those included in this documentation.


> **Tip:** Airship has built-in tools that simplify entering Handlebars expressions. See: [Dashboard tools for Handlebars](https://www.airship.com/docs/guides/personalization/simplifying-handlebars/).


## Syntax

Handlebars syntax works by wrapping a variable in curly braces. Merge fields are the most basic Handlebars expression. Insert your merge field into content by wrapping the name of your field in curly braces, e.g., `{{firstname}}`. Airship replaces the merge field (and braces) with the data specified by the merge field at send time.

> **Note:** Variables that start with a number require a special syntax, using either brackets `[]` or the `lookup` helper. For example, to use a variable named `42_answer`, use `{{ [42_answer] }}` or  `{{lookup . "42_answer"}}`.


### Block expressions

Block expressions are boolean-returning helpers that conditionally render blocks of content if their evaluation is true. These helpers use a `#` preceding the helper name and require a matching closing bracket of the same name with a `/` in front of it. See examples in [Logic/conditional statements](https://www.airship.com/docs/guides/personalization/handlebars/logic-helpers/).

## URL encoding

In HTML for email, Message Center, In-App Automation, and landing pages, values in Handlebars statements are not automatically URL-encoded. For example, if an email link includes characters that are not URL-safe and you haven't used the `urlEncode` helper, the invalid link may be replaced with a default URL, such as `https://example.com`.

When writing your own custom HTML or in any other situation where you might want to URL encode variables, you can use the `urlEncode` helper: `{{urlEncode var_name}}`.

Image and "link" properties in the Interactive Editor and message actions expect URLs. For those fields, Airship automatically URL-encodes values in Handlebars expressions to ensure valid URLs.

**When to use double braces `{{var}}`:** Use for variables that need URL encoding, such as user-generated content that might contain spaces or special characters.
   - Example: `https://www.example.com/user/{{user_name}}/{{cart_id}}`
   - If `user_name` is `John Smith`, this becomes `https://www.example.com/user/John%20Smith/123`

**When to use triple braces `{{{var}}}`:** Use for variables that contain complete URLs or are already URL-safe to avoid double-encoding.
   - Example: `{{{redirect_url}}}` 
   - If `redirect_url` is already `https://example.com/page%20one`, it remains unchanged

**Avoiding double-encoding:** Be careful not to URL-encode values that are already encoded, as this creates invalid URLs. For example, `{{"my%20value"}}` becomes the double-encoded "my%2520value" instead of the correct "my%20value".

**URL encoding push example**

```json
{
    "audience": {
        "named_user": "one_user"
    },
    "notification": {
        "android": {
          "alert": "Hi {{value_nospace}} go to https://www.example.com/{{urlEncode value_with_space}}!"
    	},
    	"actions": {
    		"open": {
    			"type": "url",
    			"content": "{{{value_full_url}}}"
    		}
    	}
    },
    "device_types": [ "android" ]
}
```


## Default handler {#def}

Use `$def` to set a default value for one or more merge field variables, so that your message will still make sense if the field is empty or doesn't exist. When using more than one variable, the handler will use the first variable value that isn't empty.

When using a default, provide both:
   * The parameters you want to use in your message
   * The default value if your variables are empty

In addition to a variable or value such as a string or a number, expressions that produce a value can also be used in the handler. For example, `($capitalize first_name)` will return the string value of `first_name` with the first letter capitalized.

**Properties**:

* `parameter` — The value or expression/variable name whose value will be used if it exists and isn't empty.
* `value` — A string to be used as a fallback default if all preceding variables or expressions were empty or did not exist.

| Format | Example | Output |
| --- | --- | --- |
| `{{$def parameter1 parameter2 parameter3... "value if keys are empty"}}` | `{{$def name "you"}}` | Welcome you! |

## Object and array notation {#dot-notation}

The user data and merge fields you use to populate a template are often nested in objects or arrays — like when using [Custom Events](https://www.airship.com/docs/developer/rest-api/ua/operations/custom-events/#addcustomevents) to populate a template in an automation rule.

Use standard dot notation to access properties in objects or an item/index in an array. For example, you could access a `productName` property in a `suggestedProduct` object using `suggestedProduct.productName`.

Use the array index to access an item at a particular location in an array. For example, if your message includes an array of objects called `suggestedProducts` for each member of your audience, you can access the first suggested product with `suggestedProducts.[0]` (array index 0).

> **Note:** Array indexes start at 0.


If you want to reference a key called `image` belonging to the first suggested product in the array, you would use `suggestedProducts.[0].image`.

### Object and array notation for Create and Send

For [Create and Send](https://www.airship.com/docs/reference/glossary/#create_and_send) CSVs, you can include complex arrays and objects in your CSV using object notation to represent object properties in the header. All values in CSV uploads, including numbers, are represented as strings and cannot be used with [math helpers](https://www.airship.com/docs/guides/personalization/handlebars/math-helpers/).

When referencing an array index, **you must wrap the array index in brackets**. Your CSV should include headers for each item in the array and each property in the object that you want to reference in your message.

For example, if you want to use an array of objects called `items` for each audience member in your CSV, your CSV will include `items.[#]` for each item in the array. If each object in the array had `name`, `image`, and `url` properties, you would add `items.[0].name, items.[0].image, items.[0].url` to your CSV, and reference additional objects in the array by incrementing the index (e.g. `items.[1]` and so on).

> **Note:** Array indexes start at 0.


If you wanted to personalize an email to members of your audience based on their addresses and the names of items they're interested in, you might format your CSV as follows:

```text
ua_address,ua_commercial_opted_in,name,address.city,address.state,items.[0].name,items.[1].name
someone@example.com,2018-04-01T18:45:30,Joe Someone,Portland,OR,Rubber Gloves,Bleach Alternative
else@example.com,2018-04-21T16:13:01,Sir Else,Seattle,WA,Flashlight,Shovel
```