Brightspot CMS Developer Guide

Theme guide

Templates

Back to Templates

Handlebars Helpers

This section describes helpers you can use in your templates. These helpers provide features beyond those available in standard Handlebars.

Comparison helpers

{{eq}}

Tests equality between two string, number, or null values. You can use this helper in block or inline context.

{{#eq person1.age person2.age}}
    The two people are the same age.
{{else}}
    The two people are not same age.
{{/eq}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{eq person1.age person2.age then='The two people are the same age' otherwise='The two people are not the same age'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

{{ge}}

Renders a block if the first argument is greater than or equal to the second argument. Supports comparing string and number values. You can use this helper in block or inline context.

{{#ge person1.age person2.age}}
    {{person1.name}} is older than or the same age as {{person2.name}}
{{else}}
    {{person1.name}} is younger than {{person2.name}}
{{/ge}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{ge person1.age person2.age then='{{person1.name}} is older than or the same age as {{person2.name}}' otherwise='{{person1.name}} is younger than {{person2.name}}'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

{{gt}}

Renders a block if the first argument is greater than the second argument. Supports comparing string and number values. You can use this helper in block or inline context.

{{#gt person1.age person2.age}}
    {{person1.name}} is older than {{person2.name}}
{{else}}
    {{person1.name}} is younger than or the same age as {{person2.name}}
{{/gt}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{gt person1.age person2.age then='{{person1.name}} is older than {{person2.name}}' otherwise='{{person1.name}} is younger than or the same age as {{person2.name}}'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

{{le}}

Renders a block if the first argument is less than or equal to the second. Supports comparing string and number values. You can use this helper in block or inline context.

{{#le person1.age person2.age}}
    {{person1.name}} is younger than or the same age as {{person2.name}}
{{else}}
    {{person1.name}} is older than {{person2.name}}
{{/le}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{le person1.age person2.age then='{{person1.name}} is younger than or the same age as {{person2.name}}' otherwise='{{person1.name}} is older than {{person2.name}}'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

{{lt}}

Renders a block if the first argument is less than the second. Supports comparing string and number values. You can use this helper in block or inline context.

{{#lt person1.age person2.age}}
    {{person1.name}} is younger than {{person2.name}}
{{else}}
    {{person1.name}} is older than or the same age as {{person2.name}}
{{/lt}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{lt person1.age person2.age then='{{person1.name}} is younger than {{person2.name}}' otherwise='{{person1.name}} is older than or the same age as {{person2.name}}'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

{{ne}}

Tests for inequality between two string, number, or null values. You can use this helper in block or inline context.

{{#ne person1.age person2.age}}
    The two people are not the same age.
{{else}}
    The two people are same age.
{{/ne}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{ne person1.age person2.age then='The two people are not the same age' otherwise='The two people are the same age'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

Logical helpers

These helpers allow for implementing logic in Handlebars. Brightspot supports the built-in helpers and adds a few additional logical helpers inspired by the open source Handlebars Helpers.

{{and}}
Renders the block if all of the given values are truthy. It optionally supports an {{else}} clause.

{{#and author.firstName author.lastName}}
<h1>{{author.firstName}} {{author.lastName}}</h1>
{{else}}
<h1>This author is anonymous</h1>
{{/and}}

In the above case, the template renders the author’s first and last name if they are both truthy values. Otherwise the template renders a message indicating the author is anonymous.

{{each}}

Iterates over a list. Inside the block you can use this to reference the element being iterated over.

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

In the above example, the this expression references the current context. Given a context which includes a list of strings people:

{
    "people": [
        "William Shakespeare",
        "Emily Dickenson",
        "Leo Tolstoy"
        "Jane Austen",
        "Agatha Christie"
    ]
}

The following is the output:

<ul class="people_list">
    <li>William Shakespeare</li>
    <li>Emily Dickenson</li>
    <li>Leo Tolstoy</li>
    <li>Jane Austen</li>
    <li>Agatha Christie</li>
</ul>

An optional {{else}} helper is available for rendering output when the list is empty.

{{#each paragraphs}}
    <p>{{this}}</p>
{{else}}
    <p class="empty">No content</p>
{{/each}}

The above snippet is equivalent to the following logic:

{{#if paragraphs}}
    {{#each paragraphs}}
        <p>{{this}}</p>
    {{/each}}
{{else}}
    <p class="empty">No content</p>
{{/if}}

The each helper injects the following private variables:

{{@index}}

Provides the current loop index. This value begins at 0 and increments with each iteration.

{{@key}}

Provides a reference to the current key name. Available when iterating over an object.

{{@first}}

Provides a boolean for implementing different rendering logic for the first item. Available when iterating over an object or list.

{{@last}}

Provides a boolean for implementing different rendering logic for the last item in the iteration context. Available when iterating over a list.

{{if}}

Conditionally renders a block. If its argument returns false, undefined, null, "", 0, or [], Brightspot does not render the block.

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

Referring to the previous snippet, if author is a falsy value, Brightspot outputs the following:

<div class="entry">
</div>

The if helper can be paired with an else helper to provide output when the if condition returns falsy.

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

{{not}}

Renders a block if the expression returns a falsy value. Equivalent to {{unless}}.

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

In the previous snippet, the warning message will be rendered if license is evaluated as a falsy value.

{{or}}

Renders the block if any of the values are truthy. It optionally supports an {{else}} clause.

{{#or author.firstName author.lastName}}
    <h1>{{author.firstName}} {{author.lastName}}</h1>
{{else}}
    <h1>This user is anonymous</h1>
{{/and}}

In the above case, the author’s first name and last name will be rendered if either the first name or last name is truthy. Otherwise the message indicating that the user is anonymous is rendered.

{{unless}}

Renders a block if the expression returns a falsy value. The unless xinfo:chunk="no" helper is used as the inverse of {{if}}. Equivalent to {{not}}.

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

In the previous snippet, the warning message will be rendered if license is evaluated as a falsy value.

(then…otherwise)

The helper {{include}} can pass parameters by value to the included template. The (then…otherwise) helpers provide a ternary assignment for the value of the passed parameter.

The syntax for (then…otherwise) is as follows:

(<condition> then=<truthy value> otherwise=<falsy value>)

{{include "ArticleBody.hbs" this headline=(headline then=headline otherwise=null)}}

Referring to the previous snippet, the parent template includes the child template ArticleBody.hbs. The call to the child template includes a value for the key headline. If headline exists in the context of this, its value is passed to the child template. If headline does not exist in the context of this, null is passed.

{{with}}

Shifts the context of the block to allow immediate access to the variables of the block’s context object.

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

In the previous snippet, if author is a truthy value the output is as follows:

<div class="entry">
    <h1>Joe Martindale</h1>
</div>

If author is a falsy value, the output is as follows:

<div class="entry">
</div>

You can include an {{else}} helper to provide output when the with condition returns falsy.

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

Math helpers

Helpers for performing arithmetic operations.

{{add}}

An inline helper which returns the sum of the arguments. Supports two or more arguments.

{{number1}} plus {{number2}} plus {{number3}} is {{add number1 number2 number3}}.

{{divide}}

An inline helper which returns the quotient of two arguments.

The quotient of {{number1}} and {{number2}} is {{divide number1 number2}}.

{{multiply}}

An inline helper which returns the product of the arguments. Supports two or more arguments.

{{number1}} multiplied by {{number2}} is {{multiple number1 number2}}.

{{remainder}}

An inline helper which returns the remainder of a division operation between two arguments.

The modulus of {{number1}} and {{number2}} is {{remainder number1 number2}}.

{{subtract}}

An inline helper which returns the difference between two arguments.

{{number1}} minus {{number2}} is {{subtract number1 number2}}.

Text helpers

Helpers for manipulating text.

{{truncate}}

Truncates strings by a number of characters or words.

Truncating by characters requires the chars argument, and optionally supports a suffix that is appended to the result if the requested length is less than the length of the input.

Expression	Result
`{{truncate "foo bar" chars=3}}`	`foo`
`{{truncate "foo bar" chars=10 suffix="…"}}`	`foo bar`
`{{truncate "foo bar" chars=3 suffix="…"}}`	`foo…`
`{{truncate "foo bar" chars=8 suffix="…"}}`	`foo bar`

Truncating by words requires the words argument, and optionally supports a suffix that is appended to the result if the requested length is less than the length of the input.

Expression	Result
`{{truncate "foo bar" words=1}}`	`foo`
`{{truncate "foo bar" words=3}}`	`foo bar`
`{{truncate "foo bar" words=1 suffix="…"}}`	`foo…`
`{{truncate "foo bar" words=3 suffix="…"}}`	`foo bar`

Utility helpers

{{cdn}}

This helper uploads static assets to a CDN.

<link rel="stylesheet" type="text/css" href="{{cdn '/MyStyles.css'}}">

<script src="{{cdn "/MyScripts.js"}}"></script>

This helper requires configuration for storage items in the Brightspot server’s context.xml. For more information, see Storage item configuration.

{{format}}

Enables conditional output by passing parameters to a message formatter in an associated properties file. The file must have the same name and be in the same directory as the template. You can use this helper to evaluate the appropriate forms for plurals and gender, and to output localized text.

For more information about the message formatter, see messageformat.js.

See also:

Resource bundles

{{get}}

Allows templates to access variables set via the {{set}} helper.

{{#set foo="bar"}}
    {{get "foo"}} equals "bar".
{{/set}}

The helper may be used to retrieve a value set by parent contexts.

{{#set lastName="Forkbeard"}}
    {{include "Child.hbs"}}
{{/set}}

Given the above usage of set, the value may be used in Child.hbs as follows:

"Sweyn {{get "lastName"}}" equals "Sweyn Forkbeard".

{{include}}

The include helper supports template reuse and composition. The behavior is similar to handlebars partials with a few differences.

It is meant for including other handlebars files using a relative path.
It does not require registering of a path or partial prior to including another file.
It does not use the same partial call syntax ({{> myPartial}}).

It supports passing a custom context as the first argument, and optionally allows passing hash parameters similar to most handlebars helpers and handlebars partials.

{{include "/path/to/AnotherFile.hbs" this parameter=value}}

{{render}}

Provides similar functionality to the {{include}}helper while providing support for Contextual rendering. This allows rendering Style variations depending on a template context.

{{render this [/core/promo/Promo.hbs]="/core/promo/FancyPromo.hbs"}}

The above example will render this using FancyPromo.hbs if this would normally have been rendered using the Promo.hbs template. This allows for developers to specify a default template to be rendered, which may be overridden in Brightspot when selecting Style variations.

{{resize}}

Provides the ability to resize an image as defined by Image sizes. Requires the first argument to be an image object and the second argument to be the name of the image size used.

{{#resize image "small"}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}">
{{/resize}}

The above example would apply a resize based on an image size named “small”, which may look like the following:

{
  "imageSizes": {
    "small": {
      "width": 100,
      "height": 100,
      "srcsetDescriptors": [
        "2x"
      ]
    }
  }
}

{{set}}

Allows templates to set a named variable, which can be retrieved using {{get}} within the block or any child context.

{{#set foo="bar"}}
    {{get "foo"}} equals "bar".
{{/set}}

This can be used as a method for passing values down through multiple child contexts without needing to explicitly pass at each occurrence of {{include}} or {{render}}.

Custom helpers

Styleguide allows you to register custom helpers which will be used by Styleguide and Brightspot when processing handlebars templates. To register your helpers, you will need to create these in a _helpers.js file in the root of your styleguide.

Below is a simple example of registering a custom uppercase helper which transforms a string argument into uppercase characters.

/* global Handlebars:false */
Handlebars.registerHelper('uppercase', function (text) {
    if (!text) return
    return text.toUpperCase()
})

In the code snippet above, a null check is important and achieves the following:

Prevents runtime errors—If url is null, undefined, or any non-string value, calling .split('/') will throw a TypeError. For instance, null.split('/') or undefined.split('/') will cause the application to crash.
Ensures robustness—By adding a null check, you ensure that your code can handle unexpected or invalid inputs gracefully. This is crucial in a real-world application where inputs can be unpredictable.
Maintains application stability—Handling edge cases like null or undefined prevents potential crashes or undefined behavior, maintaining the stability of the application.

The helper defined above can then be used in a template.

{{uppercase "Handlebars is awesome"}}

Comparison helpers

{{eq}}

Tests equality between two string, number, or null values. You can use this helper in block or inline context.

{{#eq person1.age person2.age}}
    The two people are the same age.
{{else}}
    The two people are not same age.
{{/eq}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{eq person1.age person2.age then='The two people are the same age' otherwise='The two people are not the same age'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

{{ge}}

Renders a block if the first argument is greater than or equal to the second argument. Supports comparing string and number values. You can use this helper in block or inline context.

{{#ge person1.age person2.age}}
    {{person1.name}} is older than or the same age as {{person2.name}}
{{else}}
    {{person1.name}} is younger than {{person2.name}}
{{/ge}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{ge person1.age person2.age then='{{person1.name}} is older than or the same age as {{person2.name}}' otherwise='{{person1.name}} is younger than {{person2.name}}'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

{{gt}}

Renders a block if the first argument is greater than the second argument. Supports comparing string and number values. You can use this helper in block or inline context.

{{#gt person1.age person2.age}}
    {{person1.name}} is older than {{person2.name}}
{{else}}
    {{person1.name}} is younger than or the same age as {{person2.name}}
{{/gt}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{gt person1.age person2.age then='{{person1.name}} is older than {{person2.name}}' otherwise='{{person1.name}} is younger than or the same age as {{person2.name}}'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

{{le}}

Renders a block if the first argument is less than or equal to the second. Supports comparing string and number values. You can use this helper in block or inline context.

{{#le person1.age person2.age}}
    {{person1.name}} is younger than or the same age as {{person2.name}}
{{else}}
    {{person1.name}} is older than {{person2.name}}
{{/le}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{le person1.age person2.age then='{{person1.name}} is younger than or the same age as {{person2.name}}' otherwise='{{person1.name}} is older than {{person2.name}}'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

{{lt}}

Renders a block if the first argument is less than the second. Supports comparing string and number values. You can use this helper in block or inline context.

{{#lt person1.age person2.age}}
    {{person1.name}} is younger than {{person2.name}}
{{else}}
    {{person1.name}} is older than or the same age as {{person2.name}}
{{/lt}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{lt person1.age person2.age then='{{person1.name}} is younger than {{person2.name}}' otherwise='{{person1.name}} is older than or the same age as {{person2.name}}'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

{{ne}}

Tests for inequality between two string, number, or null values. You can use this helper in block or inline context.

{{#ne person1.age person2.age}}
    The two people are not the same age.
{{else}}
    The two people are same age.
{{/ne}}

The previous snippet uses the helper in block context. In this context, an optional else helper is available.

{{ne person1.age person2.age then='The two people are not the same age' otherwise='The two people are the same age'}}

The previous snippet uses the helper in inline context. In this context, a mandatory then clause and an optional otherwise clause are available.

Logical helpers

These helpers allow for implementing logic in Handlebars. Brightspot supports the built-in helpers and adds a few additional logical helpers inspired by the open source Handlebars Helpers.

{{and}}
Renders the block if all of the given values are truthy. It optionally supports an {{else}} clause.

{{#and author.firstName author.lastName}}
<h1>{{author.firstName}} {{author.lastName}}</h1>
{{else}}
<h1>This author is anonymous</h1>
{{/and}}

In the above case, the template renders the author’s first and last name if they are both truthy values. Otherwise the template renders a message indicating the author is anonymous.

{{each}}

Iterates over a list. Inside the block you can use this to reference the element being iterated over.

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

In the above example, the this expression references the current context. Given a context which includes a list of strings people:

{
    "people": [
        "William Shakespeare",
        "Emily Dickenson",
        "Leo Tolstoy"
        "Jane Austen",
        "Agatha Christie"
    ]
}

The following is the output:

<ul class="people_list">
    <li>William Shakespeare</li>
    <li>Emily Dickenson</li>
    <li>Leo Tolstoy</li>
    <li>Jane Austen</li>
    <li>Agatha Christie</li>
</ul>

An optional {{else}} helper is available for rendering output when the list is empty.

{{#each paragraphs}}
    <p>{{this}}</p>
{{else}}
    <p class="empty">No content</p>
{{/each}}

The above snippet is equivalent to the following logic:

{{#if paragraphs}}
    {{#each paragraphs}}
        <p>{{this}}</p>
    {{/each}}
{{else}}
    <p class="empty">No content</p>
{{/if}}

The each helper injects the following private variables:

{{@index}}

Provides the current loop index. This value begins at 0 and increments with each iteration.

{{@key}}

Provides a reference to the current key name. Available when iterating over an object.

{{@first}}

Provides a boolean for implementing different rendering logic for the first item. Available when iterating over an object or list.

{{@last}}

Provides a boolean for implementing different rendering logic for the last item in the iteration context. Available when iterating over a list.

{{if}}

Conditionally renders a block. If its argument returns false, undefined, null, "", 0, or [], Brightspot does not render the block.

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

Referring to the previous snippet, if author is a falsy value, Brightspot outputs the following:

<div class="entry">
</div>

The if helper can be paired with an else helper to provide output when the if condition returns falsy.

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

{{not}}

Renders a block if the expression returns a falsy value. Equivalent to {{unless}}.

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

In the previous snippet, the warning message will be rendered if license is evaluated as a falsy value.

{{or}}

Renders the block if any of the values are truthy. It optionally supports an {{else}} clause.

{{#or author.firstName author.lastName}}
    <h1>{{author.firstName}} {{author.lastName}}</h1>
{{else}}
    <h1>This user is anonymous</h1>
{{/and}}

In the above case, the author’s first name and last name will be rendered if either the first name or last name is truthy. Otherwise the message indicating that the user is anonymous is rendered.

{{unless}}

Renders a block if the expression returns a falsy value. The unless xinfo:chunk="no" helper is used as the inverse of {{if}}. Equivalent to {{not}}.

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

In the previous snippet, the warning message will be rendered if license is evaluated as a falsy value.

(then…otherwise)

The helper {{include}} can pass parameters by value to the included template. The (then…otherwise) helpers provide a ternary assignment for the value of the passed parameter.

The syntax for (then…otherwise) is as follows:

(<condition> then=<truthy value> otherwise=<falsy value>)

{{include "ArticleBody.hbs" this headline=(headline then=headline otherwise=null)}}

{{with}}

Shifts the context of the block to allow immediate access to the variables of the block’s context object.

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

In the previous snippet, if author is a truthy value the output is as follows:

<div class="entry">
    <h1>Joe Martindale</h1>
</div>

If author is a falsy value, the output is as follows:

<div class="entry">
</div>

You can include an {{else}} helper to provide output when the with condition returns falsy.

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

Math helpers

Helpers for performing arithmetic operations.

{{add}}

An inline helper which returns the sum of the arguments. Supports two or more arguments.

{{number1}} plus {{number2}} plus {{number3}} is {{add number1 number2 number3}}.

{{divide}}

An inline helper which returns the quotient of two arguments.

The quotient of {{number1}} and {{number2}} is {{divide number1 number2}}.

{{multiply}}

An inline helper which returns the product of the arguments. Supports two or more arguments.

{{number1}} multiplied by {{number2}} is {{multiple number1 number2}}.

{{remainder}}

An inline helper which returns the remainder of a division operation between two arguments.

The modulus of {{number1}} and {{number2}} is {{remainder number1 number2}}.

{{subtract}}

An inline helper which returns the difference between two arguments.

{{number1}} minus {{number2}} is {{subtract number1 number2}}.

Text helpers

Helpers for manipulating text.

{{truncate}}

Truncates strings by a number of characters or words.

Truncating by characters requires the chars argument, and optionally supports a suffix that is appended to the result if the requested length is less than the length of the input.

Expression	Result
`{{truncate "foo bar" chars=3}}`	`foo`
`{{truncate "foo bar" chars=10 suffix="…"}}`	`foo bar`
`{{truncate "foo bar" chars=3 suffix="…"}}`	`foo…`
`{{truncate "foo bar" chars=8 suffix="…"}}`	`foo bar`

Truncating by words requires the words argument, and optionally supports a suffix that is appended to the result if the requested length is less than the length of the input.

Expression	Result
`{{truncate "foo bar" words=1}}`	`foo`
`{{truncate "foo bar" words=3}}`	`foo bar`
`{{truncate "foo bar" words=1 suffix="…"}}`	`foo…`
`{{truncate "foo bar" words=3 suffix="…"}}`	`foo bar`

Utility helpers

{{cdn}}

This helper uploads static assets to a CDN.

<link rel="stylesheet" type="text/css" href="{{cdn '/MyStyles.css'}}">

<script src="{{cdn "/MyScripts.js"}}"></script>

This helper requires configuration for storage items in the Brightspot server’s context.xml. For more information, see Storage item configuration.

{{format}}

For more information about the message formatter, see messageformat.js.

See also:

Resource bundles

{{get}}

Allows templates to access variables set via the {{set}} helper.

{{#set foo="bar"}}
    {{get "foo"}} equals "bar".
{{/set}}

The helper may be used to retrieve a value set by parent contexts.

{{#set lastName="Forkbeard"}}
    {{include "Child.hbs"}}
{{/set}}

Given the above usage of set, the value may be used in Child.hbs as follows:

"Sweyn {{get "lastName"}}" equals "Sweyn Forkbeard".

{{include}}

The include helper supports template reuse and composition. The behavior is similar to handlebars partials with a few differences.

It is meant for including other handlebars files using a relative path.
It does not require registering of a path or partial prior to including another file.
It does not use the same partial call syntax ({{> myPartial}}).

It supports passing a custom context as the first argument, and optionally allows passing hash parameters similar to most handlebars helpers and handlebars partials.

{{include "/path/to/AnotherFile.hbs" this parameter=value}}

{{render}}

Provides similar functionality to the {{include}}helper while providing support for Contextual rendering. This allows rendering Style variations depending on a template context.

{{render this [/core/promo/Promo.hbs]="/core/promo/FancyPromo.hbs"}}

{{resize}}

Provides the ability to resize an image as defined by Image sizes. Requires the first argument to be an image object and the second argument to be the name of the image size used.

{{#resize image "small"}}
    <img src="{{src}}" srcset="{{srcset}}" width="{{width}}" height="{{height}}">
{{/resize}}

The above example would apply a resize based on an image size named “small”, which may look like the following:

{
  "imageSizes": {
    "small": {
      "width": 100,
      "height": 100,
      "srcsetDescriptors": [
        "2x"
      ]
    }
  }
}

{{set}}

Allows templates to set a named variable, which can be retrieved using {{get}} within the block or any child context.

{{#set foo="bar"}}
    {{get "foo"}} equals "bar".
{{/set}}

This can be used as a method for passing values down through multiple child contexts without needing to explicitly pass at each occurrence of {{include}} or {{render}}.

BEM helpers

Warning

The BEM helpers were introduced to provide a mechanism to promote reuse using template inheritance. We’ve since promoted a new approach using template composition. These helpers are still available for the time being. However, they are no longer maintained.

The BEM helpers provided by Styleguide are available to support template inheritance and support the Block-Element-Modifier methodology.

{{block}}

Introduces a new block with an identifier. Blocks have an opening and closing helper.

{{!-- Filename Article.hbs --}}
{{#block "Article"}}
    <!-- Template markup -->
{{/block}}

As a best practice, set the identifier for a top-level {{block}} helper to the template’s base filename. Referring to the previous snippet, the template’s filename is Article.hbs, so the block identifier is Article.

This helper has two optional attributes, override and extend, for incorporating referenced templates into referring templates.

{{blockBody}}

Defines a portion of a {{block}} that you can use in an extending template.

Note

This helper is maintained for backwards compatibility. New code should not use this helper.

The following snippet in a file Article.hbs includes a {{blockBody}} helper that contains markup for a reporter’s name.

{{#block "Article"}}
    <div class="{{blockName}}">
        {{#element "headline"}}
            <div class="{{elementName}}">
                <p>{{this}}</p>
            </div>
        {{/element}}
        {{#blockBody}}
            {{#element "reporter"}}
                <div class="{{elementName}}">
                    <p>{{this}}</p>
                </div>
            {{/element}}
        {{/blockBody}}
    </div>
{{/block}}

You can include the {{blockBody}} in a template NewsArticle.hbs that extends from Article.hbs.

{{#block "NewsArticle" extend="Article.hbs"}}
    <div class="{{blockName}}">
        {{blockBody}}
            <div>Content after the block body, which only appears in a News Article.</div>
        {{/blockBody}}
    </div>
{{/block}}

{{blockName}}

Inserts the name of the nearest enclosing {{block}}. This helper is useful for assigning class names to <div> elements, an important part of implementing BEM notation.

{{#block "Article"}}
     <div class="{{blockName}}">
         <!-- Template markup -->
     </div>
{{/block}}

The previous snippet generates the following HTML.

<div class="Article">
    <!-- Template markup -->
</div>

{{element}}

Introduces a new element with an identifier. Elements have an opening and closing helper. The identifier must appear in the template’s corresponding data file.

{{#element "headline"}}
    <!-- Template markup -->
{{/element}}

noWith

{{element}} has an optional attribute noWith. When assigned true, the helper {{this}} refers to the value for the nearest enclosing {{with}} instead of the nearest enclosing {{element}}. (For an explanation of the default value for {{this}}, see {{elementName}}.)

{{#element "headline" noWith=true}}
    <div class="{{elementName}}">
        <p>{{#with shortHeadline}}{{this}}{{/with}}</p> 
    </div>
{{/element}}

Assigns the value of the key shortHeadline to {{this}}.

{{elementName}}

Inserts the name of the nearest enclosing {{block}} followed by the name of the nearest enclosing {{element}}. This helper is useful for assigning class names to HTML elements, an important part of implementing BEM notation.

{{#block "Article"}}
    <div class="{{blockName}}">
        {{#element "headline"}}
            <div class="{{elementName}}">
                <p>{{this}}</p>
            </div>
        {{/element}}
    </div>
{{/block}}

Custom helpers

Below is a simple example of registering a custom uppercase helper which transforms a string argument into uppercase characters.

/* global Handlebars:false */
Handlebars.registerHelper('uppercase', function (text) {
    return text.toUpperCase()
})

The helper defined above can then be used in a template.

{{uppercase "Handlebars is awesome"}}