Overview

AgileBuilder uses Handlebars as its template engine. This document covers all supported Handlebars syntax.

Basic Syntax

Variable Output

{{variableName}}

HTML Escaping

By default, Handlebars escapes HTML:

{{content}}  <!-- Escapes HTML -->

Unescaped Output

Use triple braces to avoid escaping:

{{{unescapedContent}}}  <!-- No escaping -->

Conditionals

if

{{#if condition}}
  Content to display
{{/if}}

if-else

{{#if condition}}
  Content when true
{{else}}
  Content when false
{{/if}}

unless

{{#unless condition}}
  Content when false
{{/unless}}

Comparison Helpers

eq (equals)

{{#if_eq value1 value2}}
  Content when equal
{{/if_eq}}

ne (not equals)

{{#if_ne value1 value2}}
  Content when not equal
{{/if_ne}}

gt / gte / lt / lte

{{#if_gt value 10}}
  value > 10
{{/if_gt}}

{{#if_gte value 10}}
  value >= 10
{{/if_gte}}

{{#if_lt value 10}}
  value < 10
{{/if_lt}}

{{#if_lte value 10}}
  value <= 10
{{/if_lte}}

Iteration

each

{{#each items}}
  {{this}}
{{/each}}

Accessing Index

{{#each items}}
  {{@index}}: {{this}}
{{/each}}

Accessing Keys

{{#each object}}
  {{@key}}: {{this}}
{{/each}}

Loop Special Variables

Variable	Description
`@index`	Current index (starting from 0)
`@key`	Current key name
`@first`	Whether this is the first element
`@last`	Whether this is the last element

with Context Switching

Switch the current object context:

{{#with user}}
  {{name}} - {{email}}
{{/with}}

Built-in Helpers

includes

Check if a value is in an array or string:

{{#if (includes tags "experimental")}}
  Experimental feature
{{/if}}

join

Join array elements into a string:

{{join items ", "}}

lower / upper

String case conversion:

{{lower name}}
{{upper name}}

trim

Remove leading and trailing whitespace:

{{trim name}}

Custom Helpers

AgileBuilder supports registering custom helpers:

// hooks/helpers.js
module.exports = {
  helpers: {
    formatDate: (date) => {
      return new Date(date).toLocaleDateString()
    }
  }
}

Partial Templates

Defining Partials

{{#*inline "header"}}
  <header>{{title}}</header>
{{/inline}}

Using Partials

{{> header title="Hello"}}

Practical Examples

Complete Example

{
  "name": "{{projectName}}",
  "version": "1.0.0",
  {{#if useTypeScript}}
  "typescript": true,
  {{/if}}
  {{#if_eq framework "react"}}
  "dependencies": {
    "react": "^18.0.0",
    {{#each features}}
    "{{this}}": "latest"{{#unless @last}},{{/unless}}
    {{/each}}
  }
  {{/if_eq}}
}

Rendered Output

When projectName="my-app", useTypeScript=true, framework="react", features=["eslint","prettier"]:

{
  "name": "my-app",
  "version": "1.0.0",
  "typescript": true,
  "dependencies": {
    "react": "^18.0.0",
    "eslint": "latest",
    "prettier": "latest"
  }
}

Next Steps

Variables Reference - Learn about variable types
Template Getting Started - Learn to create templates