Helpers

Styleguide provides a variety of helpers for helping you compose your templates and add small amounts of logic.

Comparison Helpers

The following handlebars helpers provide support for comparing values.

{{eq}}

Supports testing equality between two string, number, or null values. The syntax can be read as “equals”. It supports an optional else clause.

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

The above example uses eq as a block helper. It may also be used as an inline helper. A usage of the inline eq helper must include a then argument, and may optionally include otherwise.

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

{{ne}}

The inverse of the eq helper, and acronym for “not equals”. This is used for testing inequality between two string, number, or null values. It supports an optional else clause.

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

The above example uses ne as a block helper. It may also be used as an inline helper. A usage of the inline ne helper must include a then argument, and may optionally include otherwise.

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

{{lt}}

Renders a block if the first argument is less than the second. Supports comparing string and number values. It supports an optional else clause.

{{#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 helper may also be used as an inline helper using then and an optional otherwise argument.

{{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}}'}}

{{le}}

Renders a block if the first argument is less than or equal to the second. Supports comparing string and number values. It supports an optional else clause.

{{#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 helper may also be used as an inline helper using then and an optional otherwise argument.

{{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}}'}}

{{gt}}

Renders a block if the first argument is greater than the second argument. Supports comparing string and number values. It supports an optional else clause.

{{#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 helper may also be used as an inline helper using then and an optional otherwise argument.

{{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}}'}}

{{ge}}

Renders a block if the first argument is greater than or equal to the second. Supports comparing string and number values. It supports an optional else clause.

{{#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 helper may also be used as an inline helper using then and an optional otherwise argument.

{{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}}'}}

Logical Helpers

These helpers allow for implementing logic in Handlebars. Styleguide 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 user is anonymous</h1>
{{/and}}

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

{{if}}

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

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

In the above scenario if author is a falsy value the above template would be rendered as:

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

The if helper can be paired with an else section to provide a rendered 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}}

The not helper is used as the inverse of the if helper. This is equivalent to the unless helper. The block will be rendered if the expression returns a falsy value.

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

In the example above, 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.

{{with}}

The {{with}} helper is similar to the if helper above, with one key difference. It shifts the context of the block to allow immediate access to the variables of the block context object.

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

In the above scenario if author is a falsy value the above template would be rendered as:

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

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

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

{{unless}}

Equivalent to the not helper. The unless helper is used as the inverse of the if helper. The block will be rendered if the expression returns a falsy value.

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

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

{{each}}

Support for iterating over a list is available using the each helper. 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": [
        "Ryan Anderson",
        "Rich Fredericks",
        "Hyoo Lim"
        "Rohit Monga",
        "Dan Slaughter"
    ]
}

Handlebars will render the output as:

<ul class="people_list">
    <li>Ryan Anderson</li>
    <li>Rich Fredericks</li>
    <li>Hyoo Lim</li>
    <li>Rohit Monga</li>
    <li>Dan Slaughter</li>
</ul>

Note

The each helper also supports an {{else}} section for when you want to render something different 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 private variables to which provide some additional information while iterating.

{{@index}}

This variable can be used within an each block to access the current loop index. This value begins at 0 and increments with each iteration.

{{@key}}

This variable can only be used when the iteration context is an object, and provides a reference to the current key name.

{{@first}}

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

{{@last}}:

Provides a boolean for implementing different rendering logic for the last item in the iteration context. This is available only when the iteration context is a list.

{{partition}}

Creates sublists from a list object which allows for creating groups of items of a specific size. The size of the partitions is defined by the size argument.

1
2
3
4
5
6
7
8
9
    {{#partition items size=3}}
        <div class="row">
            {{#each this}}
                <div class="column">
                    {{this}}
                </div>
            {{/each}}
        </div>
    {{/partition}}

Given a context of an array of 6 strings:

{
    "items": [
        "Dan Sisan",
        "Ping Pan",
        "Ben London"
        "Rob Seeger",
        "Lee Teague",
        "Brendan Brelsford"
    ]
}

Handlebars will render the output as:

<div class="row">
    <div class="column">
        Dan Sisan
    </div>

    <div class="column">
        Ping Pan
    </div>

    <div class="column">
        Ben London
    </div>
</div>

<div class="row">
    <div class="column">
        Rob Seeger
    </div>

    <div class="column">
        Lee Teague
    </div>

    <div class="column">
        Brendan Brelsford
    </div>
</div>

Math Helpers

Helpers for dealing with numbers.

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

{{subtract}}

An inline helper which returns the difference between two arguments.

{{number1}} minus {{number2}} is {{subtract 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}}

{{divide}}

An inline helper which returns the quotient of two arguments.

The quotient of {{number1}} and {{number2}} is {{divide 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}}

Text Helpers

Helpers for dealing with text.

{{truncate}}

Supports truncating strings by number of characters or number of words.

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

{{truncate "foo bar" chars=3}} result in "foo".
{{truncate "foo bar" chars=10 suffix="…"}} results in "foo bar".
{{truncate "foo bar" chars=3 suffix="…"}} results in "foo...".

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

{{truncate "foo bar" words=1}} results in "foo".
{{truncate "foo bar" words=3}} results in "foo bar".
{{truncate "foo bar" words=1 suffix="…"}} results in "foo...".
{{truncate "foo bar" words=3 suffix="…"}} results in "foo bar".

Utility Helpers

{{cdn}}

This helper is provided to upload static assets to a CDN as configured on the server.

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

Note

This helper is a noop when running a standalone Styleguide server. The behavior relies on a Brightspot server with a Storage Configuration. For more information on configuring a CDN, 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 file. 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:

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

BEM Helpers

Note

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

A block helper which defines a new BEM block.

{{!-- 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}}

A block helper which allows definition of the body of a block as defined by the {{block}}

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

Note

This helper should be used sparingly, as it is not often necessary and is only still available due to backwards compatibility and convenience reasons.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{{#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>
     </div>
{{/block}}

{{blockName}}

Inserts the name of the nearest enclosing {{block}}. This helper is useful for assigning class names to HTML elements, preventing the manual repetition of the block name.

{{#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 noWith is 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}}.)

1
2
3
4
5
{{#element "headline" noWith=true}}
    <div class="{{elementName}}">
        <p>{{#with shortHeadline}}{{this}}{{/with}}</p>
    </div>
{{/element}}

In the previous snippet, line 3 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.

1
2
3
4
5
6
7
8
9
{{#block "Article"}}
    <div class="{{blockName}}">
        {{#element "headline"}}
            <div class="{{elementName}}">
                <p>{{this}}</p>
            </div>
        {{/element}}
    </div>
{{/block}}

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) {
     return text.toUpperCase()
})

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

{{uppercase "Handlebars is awesome"}}