Handlebars basics

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.

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.

URL encoding

Some properties in Airship messages expect URLs — message actions, image and “link” properties in the Interactive Editor, etc. For these fields, items in double-curly braces are URL-encoded, e.g., my value becomes my%20value.

• Use double braces to reference parameters that need URL encoding: https://www.example.com/user/{{user_name}}/{{cart_id}}

• Use triple braces to escape URL encoding, such as when referencing a variable or complete URL that is already URL-safe: {{{url}}}

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}}.

For email content, double braces are not URL-encoded, regardless of whether you use the WYSIWYG editor or custom HTML. The urlEncode helper is recommended when using parameters in email links. If an email link includes characters that are not URL-safe, the invalid link may be replaced with a default URL, such as https://google.com.

{
    "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

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 who’s 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.

Object and array 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 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).

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 inline lists

For Inline ListsAn ad-hoc, CSV-formatted list of email, SMS, app, web, or open channel addresses that you want to register and send a message to. Unlike static lists or segments, you upload this list when creating your message. Airship registers new addresses in the list as channels when you send the message., you can include complex arrays and objects in your CSV using object notation to represent object properties in the header.

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).

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:

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