Helpers

#if

You can use the if helper to conditionally render a block. If its argument returns false, undefined, null, "", 0, or [], Handlebars will not render the block.

<div>
    {{#if author}}
        <h1>{{firstName}} {{lastName}}</h1>
    {{/if}}
</div>

When you pass the following input to the above template:

{
  author: true,
  firstName: "Yehuda",
  lastName: "Katz",
}

This will produce the result as below:

<div>
    <h1>Yehuda Katz</h1>
</div>

If the input is an empty JSONObject {}, then author will become undefined and if condition fails, resulting in the output as follow:

<div></div>

When using a block expression, you can specify a template section to run if the expression returns a falsy value. The section, marked by else is called an “else section”.

<div>
    {{#if author}}
        <h1>{{firstName}} {{lastName}}</h1>
    {{else}}
        <h1>Unknown Author</h1>
    {{/if}}
</div>

#includeZero

The includeZero=true option may be set to treat the conditional as not empty. This effectively determines if 0 is handled by the positive or negative path.

{{#if 0 includeZero=true}}
  <h1>Does render</h1>
{{/if}}

#unless

You can use the unless helper as the inverse of the if helper. Its block will be rendered if the expression returns a falsy value.

<div>
    {{#unless license}}
        <h3 class="warning">WARNING: This entry does not have a license!</h3>
    {{/unless}}
</div>

If looking up license under the current context returns a falsy value, Handlebars will render the warning. Otherwise, it will render nothing.

#each

You can iterate over a list using the built-in each helper. Inside the block, you can use this to reference the element being iterated over.

<ul>
  {{#each people}}
    <li>{{this}}</li>
  {{/each}}
</ul>

When used with this context:

{
  people: [
    "Yehuda Katz",
    "Alan Johnson",
    "Charles Jolley",
  ]
}

Will result in:

<ul>
    <li>Yehuda Katz</li>
    <li>Alan Johnson</li>
    <li>Charles Jolley</li>
</ul>

You can use the this expression in any context to reference the current context.

You can optionally provide an else section which will display only when the list is empty.

{{#each paragraphs}}
    <p>{{this}}</p>
{{else}}
    <p>No content</p>
{{/each}}

When looping through items in each, you can optionally reference the current loop index via {{@index}}.

{{#each array}} {{@index}}: {{this}} {{/each}}

Additionally for object iteration, {{@key}} references the current key name:

{{#each object}} {{@key}}: {{this}} {{/each}}

The first and last steps of iteration are noted via the @first and @last variables when iterating over an array.

Nested each blocks may access the iteration variables via depth based paths. To access the parent index, for example, {{@../index}} can be used.

#with

The with-helper allows you to change the evaluation context of template-part.

{{#with person}}
    {{firstname}} {{lastname}}
{{/with}}

When used with this context:

{
  person: {
    firstname: "Yehuda",
    lastname: "Katz",
  }
}

Will result in:

Yehuda Katz

with can also be used with block parameters to define known references in the current block. The example above can be converted to:

{{#with city as | city |}}
  {{#with city.location as | loc |}}
    {{city.name}}: {{loc.north}} {{loc.east}}
  {{/with}}
{{/with}}

When used with this context:

{
  city: {
    name: "San Francisco",
    summary: "San Francisco is the <b>cultural center</b> of <b>Northern California</b>",
    location: {
      north: 37.73,
      east: -122.44
    },
    population: 883305
  }
}

Will result in:

 San Francisco: 37.73 -122.44

Which allows for complex templates to potentially provide clearer code than ../ depthed references allow for.

You can optionally provide an {{else}} section which will display only when the passed value is empty.

{{#with city}}
    {{city.name}} (not shown because there is no city)
{{else}}
    No city found
{{/with}}

#lookup

The lookup helper allows for dynamic parameter resolution using Handlebars variables.

This is useful for resolving values for array indexes.

{{#each people}}
  {{.}} lives in {{lookup ../cities @index}}
{{/each}}

It can also be used to lookup properties of object based on data from the input. The following is a more complex example that uses lookup in a sub-expression to change the evaluation context to another object based on a property-value.

{{#each persons as | person |}}
  {{name}} lives in {{#with (lookup ../cities [resident-in])~}}
    {{name}} ({{country}})
  {{/with}}
{{/each}}

When used with this context:

{
  persons: [
    {
      name: "Nils",
      "resident-in": "darmstadt"
    },
    {
      name: "Yehuda",
      "resident-in": "san-francisco"
    }
  ],
  cities: {
    darmstadt: {
      name: "Darmstadt",
      country: "Germany"
    },
    "san-francisco": {
      name: "San Francisco",
      country: "USA"
    }
  }
}

Will result in:

Nils lives in Darmstadt (Germany)
Yehuda lives in San Francisco (USA)