More about IdealDoc functions

1 Changing the context
2 Literal segments
3 HTML-escaping
4 Helper Functions
5 Literal arguments
6 Disambiguating helpers calls and property lookup
7 Block Helpers

Changing the context

Some helpers like #with and #each allow you to dive into nested objects. When you include ../ segments in your path, IdealDoc will change back into the parent context.

{{#each people}}
    {{../prefix}} {{firstname}} 
{{/each}}

Even though the name is printed while in the context of a comment, it can still go back to the main context (the root-object) to retrieve the prefix.

The exact value that ../ will resolve to varies based on the helper that is calling the block. Using ../ is only necessary when context changes. Children of helpers such as {{#each}} would require the use of ../ while children of helpers such as {{#if}} do not.

{{permalink}}
{{#each comments}}
  {{../permalink}}
  {{#if title}}
    {{../permalink}}
  {{/if}}
{{/each}}

In this example all of the above reference the same prefix value even though they are located within different blocks. IdealDoc also allows for name conflict resolution between helpers and data fields via a this reference:

Literal segments

Identifiers may be any unicode character except for the following:

Whitespace ! " # % & ' ( ) * + , . / ; < = > @ [ \\ ] ^ ` { | } ~

In addition, the words true, false, null and undefined are only allowed in the first part of a path expression.

To reference a property that is not a valid identifier, you can use segment-literal notation, [. You may not include a closing ] in a path-literal, but all other characters are allowed.

JavaScript-style strings, " and ', may also be used instead of [ pairs.template

{{!-- wrong: {{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]}}

HTML-escaping

In IdealDoc, the values returned by the {{expression}} are HTML-escaped. Say, if the expression contains &, then the returned HTML-escaped output is generated as &. If you don't want IdealDoc to escape a value, use the "triple-stash", {{{:

In the below template, you can learn how to produce the HTML escaped and raw output.

Pass the special characters to the templateinput

Expressions enclosed by "triple-stash" ({{{) produce the raw output. Otherwise, HTML-escaped output is generated as below.

output

Helper Functions

Functions or Helpers provide additional functionality to the template.

Literal arguments

Helper calls may also have literal values passed to them either as parameter arguments or hash arguments. Supported literals include numbers, strings, true, false, null and undefined. Strings always need to be enclosed in quotes “my string” while numbers, booleans and null or undefined are passed without quotes.

Disambiguating helpers calls and property lookup

If a helper is registered by the same name as a property of an input object, the helper has priority over the input property. If you want to resolve the input property instead, you can prefix its name with ./ or this.

Block Helpers

Block helpers are built in functions which operate on a whole block of text. A Block is defined by a starting directive #<directive name> and an ending directive /<directive name>. The most common block functions are used for loops (each) and conditions (if).

IdealDoc Q