Skip to content

template-reference.md

Latest commit

 

History

History
231 lines (187 loc) · 4.51 KB

template-reference.md

File metadata and controls

231 lines (187 loc) · 4.51 KB

Templates

Templates are documents that describe an output format such as HTML. They allow the ultimate representation of a data structure (or "data dictionary") to be specified independently of the data itself, promoting a clear separation of responsibility.

Template documents include "markers" that are replaced with values from the data dictionary when the template is processed:

Each is discussed in more detail below.

Variables

Variable markers inject a named value from the data dictionary into the output. For example:

{
  "a": "A",
  "b": {
    "c": "C"
  },
  "d": [
    1, 
    2, 
    3
  ]
}
<!-- A -->
<p>{{a}}</p>

Nested values can be referred to by path:

<!-- C -->
<p>{{b/c}}</p>

Within a repeating or conditional section, the "." character can be used to refer to the current element:

<!-- 1, 2, 3 -->
{{#d}}
<p>{{.}}</p>
{{/d}}

Modifiers

Modifiers are used to transform a variable's representation before it is written to the output stream. They are specified as shown below and are invoked in declaration order. An optional argument may be included to provide additional information to a modifier:

{{variable:modifier1:modifier2:modifier3=argument:...}}

All templates support the format modifier, which can be used to apply a format string or one of the following standard formats:

  • currency
  • percent
  • shortDate
  • mediumDate
  • longDate
  • fullDate
  • isoDate
  • shortTime
  • mediumTime
  • longTime
  • fullTime
  • isoTime
  • shortDateTime
  • mediumDateTime
  • longDateTime
  • fullDateTime
  • isoDateTime

For example:

{{date:format=shortDate}}

Applications may also define their own custom modifiers.

Repeating Sections

Repeating section markers define a section of content that is repeated once for every element in a sequence of values. For example:

{
  "a": "A",
  "b": [
    {
      "c": 1
    },
    {
      "c": 2
    },
    {
      "c": 3
    }
  ]
}
<!-- 1, 2, 3 -->
{{#b}}
<p>{{c}}</p>
{{/b}}

Named values are inherited from the parent context:

<!-- A1, A2, A3 -->
{{#b}}
<p>{{a}}{{c}}</p>
{{/b}}

Conditional Sections

Conditional section markers define a section of content that is only rendered if the named value exists in the data dictionary. Additionally, for iterable, map, and string content, the value must not be empty. For numeric data, the value must not be 0. For booleans, the value must be true.

For example:

{
  "a": "A",
  "b": {
    "c": 1,
    "d": 2,
    "e": 3
  }
}
<!-- 1, 2, 3 -->
{{?b}}
<p>{{c}}, {{d}}, {{e}}</p>
{{/b}}

As with repeating sections, parent values are inherited:

<!-- A1, A2, A3 -->
{{?b}}
<p>{{a}}{{c}}, {{a}}{{d}}, {{a}}{{e}}</p>
{{/b}}

Inverted Sections

Inverted section markers define a section of content that is only rendered if the named value does not exist in the data dictionary. Additionally, for iterable, map, and string content, the value must be empty. For numeric data, the value must be 0. For booleans, the value must be false.

For example:

{
  "a": [
  ]
}
<!-- not found -->
{{^a}}
<p>not found</p>
{{/a}}

Resources

Resource markers inject a localized value into the output. For example:

{
  "a": 123
}
a = Å
<!-- 123 Å -->
{{a}} {{$a}}

Includes

Include markers import content defined by another template. For example:

{
  "a": 123
}
<!DOCTYPE html>
<html>
<body>
{{>include.html}}
</body>
</html>
<!-- 123 -->
<p>{{a}}</p>

Self-referencing includes are supported and can be used to facilitate recursion.

Comments

Comment markers provide informational text about a template's content. They are not included in the final output:

{
  "a": 123
}
<!-- 123 -->
<p>{{a}} {{!456}}</p>