Articles in this section

Nested block helpers and raw blocks

Tom Santiago
Updated

Block helpers in Handlebars templates can reference variables and literal values, and you can nest one block helper inside another. A block helper wraps content between an opening tag, such as {{#if}}, and a matching closing tag, such as {{/if}}. Raw blocks let you output content literally, without evaluating any Handlebars expressions inside them. Builders use these patterns in field mappings, response mappings, HTTP request bodies, and dynamic API paths to build conditional and templated output.

Reference variables and literal values

A block helper can render a referenced variable in one branch and a literal value in another. This example renders contact.phone when it has a value, and a literal fallback message when it doesn't. Because contact.phone has a value, the helper renders the phone number.

Template

{{#if contact.phone}}{{contact.phone}}{{else}}Phone number not found{{/if}}

Context

{
  "contact": {
    "name": "Jack Parsons Laboratory",
    "phone": "310-555-1234"
  }
}

Output

310-555-1234

Nest block helpers

You can place one block helper inside another to evaluate a second condition only when the first is true. This example renders True only when customer1 equals 2 and customer2 equals 5. Because both conditions are true, the helper renders True.

Template

{{#compare customer1 "==" "2"}}
  {{#compare customer2 "==" "5"}}
    True
  {{else}}
    False
  {{/compare}}
{{else}}
  False
{{/compare}}

Context

{
  "customer1": "2",
  "customer2": "5"
}

Output

True

Raw blocks

Raw blocks work like block helpers, except the content between the tags is treated as a literal string and isn't evaluated. Define a raw block with four braces on the opening and closing tags: {{{{name}}}} and {{{{/name}}}}. Use a raw block when you need to output Handlebars-style syntax literally, such as when generating a template that itself contains double braces.

In this example, the content {{Samantha}} is rendered as literal text instead of being evaluated as a variable.

Template

{{{{name}}}}
  {{Samantha}}
{{{{/name}}}}

Context

{}

Output

{{Samantha}}

Notes and constraints

  • Match each opening block tag with its closing tag, for example {{#if}} with {{/if}} and {{#compare}} with {{/compare}}.
  • Raw blocks use four braces on both tags: {{{{name}}}} and {{{{/name}}}}.
  • Whitespace and line breaks inside a block render literally in the output. Remove extra spaces and line breaks when you don't want them in the result.