handlebars

Handlebars

Expressions

• Handlebars HTML-escapes variables are returned by a {{expression}}
• If you don't want to escape a value, use raw rendering: {{{
• (Special) variables need to be surrounded by {{ and }} but not within a control sequence (like {{#if @first}})
• Path expressions: {{person.firstname}}
• {{!-- This is a comment --}} but {{! This as well }}
  • Use the former if your comment includes }} or handlebars tokens
• To make the comment appear in the output use html comments: <!-- This comment will be in the output -->

Accessing properties

Use [] for accessing lists/arrays:

{{!-- wrong: {{array.0.item}} --}}
correct: array.[0].item: {{array.[0].item}}
correct: array.[0].item: {{array.[0].[item]}}

{{!-- wrong: {{array.[0].item-class}} --}}
correct: array.[0].[item-class]: {{array.[0].[item-class]}}

{{!-- wrong: {{./true}}--}}
correct: ./[true]: {{./[true]}}

Whitespace control

Lstrip/rstrip

Lstrip or rstrip whitespaces with ~:

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

Remove newlines

{{#each persons}}
	{{~this.name~}}{{~^~}}
{{/each}}

Exaping and raw blocks

Escaping means basically that this specific part will not be compiled.

\{{escaped}}
{{{{raw}}}}
  {{escaped}}
{{{{/raw}}}}

Built-in helpers

#if

• false == undefined == null == "" == 0 == []
• includeZero=true: treat the conditional as not empty. Determines if 0 is handled by the positive or negative path.

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


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

#unless

Inverse #if:

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

#each

For-each loop:

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

• {{this}}/{{.}} references to the current loop object
• {{@index}} will return the current loop index
• {{@key}} returns the current key name for object iteration
• {{@first}}/{{@last}}: True if first/last iteration in loop
• Nested loops can access higher hirarchies via {{@../index}}

-> see also @data variables

Named parameters:

{{#each users as |user userId|}}
  Id: {{userId}} Name: {{user.name}}
{{/each}}

• user will hold the value
• userId will hold the index

#with

{{#with person}}
{{firstname}} {{lastname}}
{{else}}
No person found!
{{/with}}
-> Else will be executed when `person` is not existing


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

-> Can be used to make a variable available within the #with block (i.e. city is made available within the inner block) -> this avoids usage of the ../ syntax

lookup

Value look-up

Allows to look-up some value:

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

Input:

{
  people: ["Nils", "Yehuda"],
  cities: [
    "Darmstadt",
    "San Francisco",
  ],
}

-> {{lookup ../cities @index}} goes one level up, into cities and @index selects the matching index provided by the loop over people

Property look-up

Looks-up a key (the value of persons/resident-in) in cities and prints its values (name + country):

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

Input:

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

log

Logging to the console strings and variables:

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

Set a log level:

{{log "debug logging" level="debug"}}

-> Levels: debug/info (=default)/warn/error

Partials

Inline partials

{{#*inline "myPartial"}}
  My Content
{{/inline}}
{{#each people}}
  {{> myPartial}}
{{/each}}

-> Will always print My Content

{{#*inline "myPartial"}}
  {{firstname}}
{{/inline}}
{{#each people}}
  {{> myPartial}}
{{/each}}

-> Will print the value of each firstname

Input:

{
  people: [
    { firstname: "Nils" },
    { firstname: "Yehuda" },
  ],
}

Each inline partial is available to the current block and all children, including execution of other partials.

Nested helpers

TODO