# Built-in 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.

template

<div class="entry">
{{#if author}}
<h1>{{firstName}} {{lastName}}</h1>
{{/if}}
</div>

When you pass the following input to the above template

input

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

This will produce the result as below:

output

<div class="entry">
<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 class="entry"></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".

template

<div class="entry">
{{#if author}}
<h1>{{firstName}} {{lastName}}</h1>
{{else}}
<h1>Unknown Author</h1>
{{/if}}
</div>

# Sub-Expressions

Helpers are the proposed way to add custom logic to templates. You can write any helper and use it in a sub-expression.

For example, in checking for initialization of a variable the built-in #if check might not be appropriate as it returns false for empty collections (see Utils.isEmpty).

You could write a helper that checks for "undefined" such as:

preparationScript

Handlebars.registerHelper('isdefined', function (value) {
  return value !== undefined;
});

Then use your helper as a sub-expression:

template

{{#if (isdefined value1)}}true{{else}}false{{/if}}
{{#if (isdefined value2)}}true{{else}}false{{/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.

template

<div class="entry">
{{#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.

template

<ul class="people_list">
  {{#each people}}
    <li>{{this}}</li>
  {{/each}}
</ul>

when used with this context:

input

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

will result in:

output

<ul class="people_list">
    <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.

template

{{#each paragraphs}}
<p>{{this}}</p>
{{else}}
<p class="empty">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. When iterating over an object only the @first is available. 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.

template

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

when used with this context:

input

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

will result in:

output

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

template

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

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.

template

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

input

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

# lookup

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

This is useful for resolving values for array indexes.

template

{{#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.

template

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

# log

The log helper allows for logging of context state while executing a template.

template

{{log 'this is a simple log output'}}

It delegates to Handlebars.logger.log which may be overridden to perform custom logging.

Any number of arguments may be passed to this method and all will be forwarded to the logger.

template

{{log 'firstname' firstname 'lastname' lastname}}

The log level may be set using the level hash parameter. Supported values are debug, info, warn, and error. When omitted, info is the default value,

Logging is conditional based on the level and to value set in Handlebars.logger.level, which defaults to info. All log statements at or above the current level will be output.

template

{{log "debug logging" level="debug"}}
{{log "info logging" level="info"}}
{{log "info logging is the default"}}
{{log "logging a warning" level="warn"}}
{{log "logging an error" level="error"}}

← Block Helpers Hooks →