You can use the if helper to conditionally render a block. If its argument returns false, undefined, null, "",
0, or [], DocumentEngine will not render the block.
<div class="entry">
{{#if author}}
<h1>{{firstName}} {{lastName}}</h1>
{{/if}}
</div>When you pass the following input to the above template
{
author: true,
firstName: "Yehuda",
lastName: "Katz",
}
This will produce the result as below:
<div class="entry">
<h1>Yehuda Katz</h1>
</div>If the input is an empty JSONObject {}, then author will become undefined and if condition fails, resulting in
the output as follow:
<div class="entry"></div>
When using a block expression, you can specify a template section to run if the expression returns a falsy value. The
section, marked by else is called an "else section".
<div class="entry">
{{#if author}}
<h1>{{firstName}} {{lastName}}</h1>
{{else}}
<h1>Unknown Author</h1>
{{/if}}
</div>The includeZero=true option may be set to treat the conditional as not empty.
This effectively determines if 0 is handled by the positive or negative path.
{{#if 0 includeZero=true}}
<h1>Does render</h1>
{{/if}}
Helpers are the proposed way to add custom logic to templates. You can write any helper and use it in a sub-expression.
For example, in checking for initialization of a variable the built-in #if check might not be appropriate as it
returns false for empty collections (see Utils.isEmpty).
You could write a helper that checks for "undefined" such as:
DocumentEngine.registerHelper('isdefined', function (value) {
return value !== undefined;
});
Then use your helper as a sub-expression:
{{#if (isdefined value1)}}true{{else}}false{{/if}}
{{#if (isdefined value2)}}true{{else}}false{{/if}}
You can use the unless helper as the inverse of the if helper. Its block will be rendered if the expression returns
a falsy value.
<div class="entry">
{{#unless license}}
<h3 class="warning">WARNING: This entry does not have a license!</h3>
{{/unless}}
</div>If looking up license under the current context returns a falsy value, DocumentEngine will render the warning. Otherwise,
it will render nothing.
You can iterate over a list using the built-in each helper. Inside the block, you can use this to reference the
element being iterated over.
<ul class="people_list">
{{#each people}}
<li>{{this}}</li>
{{/each}}
</ul>when used with this context:
{
people: [
"Yehuda Katz",
"Alan Johnson",
"Charles Jolley",
],
}
will result in:
<ul class="people_list">
<li>Yehuda Katz</li>
<li>Alan Johnson</li>
<li>Charles Jolley</li>
</ul>You can use the this expression in any context to reference the current context.
You can optionally provide an else section which will display only when the list is empty.
{{#each paragraphs}}
<p>{{this}}</p>
{{else}}
<p class="empty">No content</p>
{{/each}}When looping through items in each, you can optionally reference the current loop index via {{@index}}.
{{#each array}} {{@index}}: {{this}} {{/each}}
Additionally for object iteration, {{@key}} references the current key name:
{{#each object}} {{@key}}: {{this}} {{/each}}
The first and last steps of iteration are noted via the @first and
@last variables when iterating over an array.
Nested each blocks may access the iteration variables via depth based paths. To access the parent index, for example,
{{@../index}} can be used.
The with-helper allows you to change the evaluation context of template-part.
{{#with person}}
{{firstname}} {{lastname}}
{{/with}}
when used with this context:
{
person: {
firstname: "Yehuda",
lastname: "Katz",
},
}
will result in:
Yehuda Katz
with can also be used with block parameters to define known references in the current block. The example above can be
converted to
{{#with city as | city |}}
{{#with city.location as | loc |}}
{{city.name}}: {{loc.north}} {{loc.east}}
{{/with}}
{{/with}}Which allows for complex templates to potentially provide clearer code than ../ depthed references allow for.
You can optionally provide an {{else}} section which will display only when the passed value is empty.
{{#with city}}
{{city.name}} (not shown because there is no city)
{{else}}
No city found
{{/with}}
{
person: {
firstname: "Yehuda",
lastname: "Katz",
},
}
The lookup helper allows for dynamic parameter resolution using DocumentEngine variables.
This is useful for resolving values for array indexes.
{{#each people}}
{{.}} lives in {{lookup ../cities @index}}
{{/each}}
It can also be used to lookup properties of object based on data from the input. The following is a more complex example
that uses lookup in a sub-expression to change the evaluation context to another object based on a property-value.
{{#each persons as | person |}}
{{name}} lives in {{#with (lookup ../cities [resident-in])~}}
{{name}} ({{country}})
{{/with}}
{{/each}}
The log helper allows for logging of context state while executing a template.
{{log 'this is a simple log output'}}
It delegates to DocumentEngine.logger.log which may be overridden to perform custom logging.
Any number of arguments may be passed to this method and all will be forwarded to the logger.
{{log 'firstname' firstname 'lastname' lastname}}
The log level may be set using the level hash parameter. Supported values are debug, info, warn, and error. When omitted, info is the default value,
Logging is conditional based on the level and to value set in DocumentEngine.logger.level, which defaults to info. All
log statements at or above the current level will be output.
{{log "debug logging" level="debug"}}
{{log "info logging" level="info"}}
{{log "info logging is the default"}}
{{log "logging a warning" level="warn"}}
{{log "logging an error" level="error"}}
The is helper is a function that you can use in your DocumentEngine templates to compare two values and return the result of the comparison.
To use the is helper, you can include it in your template like this:
{{#if (is value1 operator value2)}}
...
{{else}}
...
{{/if}}
This example uses the is helper within an if block, which allows you to specify different output depending on the result of the comparison. If the comparison returns true, the output of the options.fn function (the code within the if block) is returned. If the comparison returns false, the output of the options.inverse function (the code within the else block) is returned.
The is helper takes three arguments:
value1: The first value to compare.operator: The comparison operator to use. This can be one of the following values:==: Returns true if value1 is equal to value2.===: Returns true if value1 is strictly equal to value2.>: Returns true if value1 is greater than value2.<: Returns true if value1 is less than value2.>=: Returns true if value1 is greater than or equal to value2.<=: Returns true if value1 is less than or equal to value2.!=: Returns true if value1 is not equal to value2.!==: Returns true if value1 is not strictly equal to value2.$>: Returns true if value1 contains value2, case-insensitive.<$: Returns true if value2 contains value1, case-insensitive.$$>: Returns true if value1 contains value2, case-sensitive.<$$: Returns true if value2 contains value1, case-sensitive.<#: Returns true if value1 is contained in an array value2.&&: Returns true if arrays value1 and value2 have at least one element in common.value2: The second value to compare.Here are some examples of how you might use the is helper in your templates:
{{#if (is value1 '==' value2)}}
<p>Value 1 is equal to value 2.</p>
{{else}}
<p>Value 1 is not equal to value 2.</p>
{{/if}}
{{#if (is value1 '>' value2)}}
<p>Value 1 is greater than value 2.</p>
{{else}}
<p>Value 1 is not greater than value 2.</p>
{{/if}}
{{#if (is value1 '!=' value2)}}
<p>Value 1 is not equal to value 2.</p>
{{else}}
<p>Value 1 is equal to value 2.</p>
{{/if}}
The and helper is a function that you can use in your DocumentEngine templates to perform a logical AND operation on any number of arguments. It returns true if all of the arguments are truthy, and false otherwise.
To use the and helper, you can include it in your template like this:
{{#if (and condition1 condition2 ... conditionN)}} <p>All conditions are true.</p> {{else}} <p>At least one condition is false.</p> {{/if}}This example uses the and helper within an if block, which allows you to specify different output depending on the result of the AND operation.
The and helper takes any number of arguments, and returns true if all of them are truthy.
The or helper is a function that you can use in your DocumentEngine templates to perform a logical OR operation on any number of arguments. It returns true if at least one of the arguments is truthy, and false otherwise.
To use the or helper, you can include it in your template like this:
{{#if (or condition1 condition2 ... conditionN)}} <p>At least one condition is true.</p> {{else}} <p>All conditions are false.</p> {{/if}}This example uses the or helper within an if block, which allows you to specify different output depending on the result of the OR operation.
The or helper takes any number of arguments, and returns true if at least one of them is truthy.
The formatNumber helper is a function that you can use in your DocumentEngine templates to format a number to a specified string format. It uses the numeral.js library to perform the formatting.
To use the formatNumber helper, you can include it in your template like this:
<p>The number is {{formatNumber number format}}.</p>This example outputs a <p> element containing the formatted number.
The formatNumber helper takes two arguments:
number: The number to be formatted. This can be a JavaScript number or a string that can be parsed by the numeral.js library.format: The string format to use for the number. This can be any valid numeral.js format string, such as 0,0 for a number with thousands separators, or 0.00% for a number with a percentage symbol.Here are some examples of how you might use the formatNumber helper in your templates:
<p>The number is {{formatNumber number '0,0'}}.</p><p>The number is {{formatNumber number '0.00%'}}.</p><p>The number is {{formatNumber number '$0,0.00'}}.</p>In the first example, the formatNumber helper is used to format the number variable using the 0,0 format, which will output something like The number is 10,000. In the second example, the formatNumber helper is used to format the number variable using the 0.00% format, which will output something like The number is 10.00%. In the third example, the formatNumber helper is used to format the number variable using the $0,0.00 format, which will output something like The number is $10,000.00.
The date helper is a function that you can use in your DocumentEngine templates to format a date to a specified string format. It uses the moment.js library to perform the formatting.
To use the date helper, you can include it in your template like this:
<p>The date is {{date date format}}.</p>This example outputs a <p> element containing the formatted date.
The date helper takes two arguments:
date: The date to be formatted. This can be a JavaScript Date object or a string that can be parsed by the moment.js library.format: The string format to use for the date. This can be any valid moment.js format string, such as DD/MM/YYYY for a date in the format dd/mm/yyyy, or dddd, MMMM Do YYYY, h:mm:ss a for a full date and time in a long format.Here are some examples of how you might use the date helper in your templates:
<p>The date is {{date date 'DD/MM/YYYY'}}.</p><p>The date is {{date date 'dddd, MMMM Do YYYY, h:mm:ss a'}}.</p><p>The date is {{date date 'YYYY-MM-DD'}}.</p>In the first example, the date helper is used to format the date variable using the DD/MM/YYYY format, which will output something like The date is 10/12/2022. In the second example, the date helper is used to format the date variable using the dddd, MMMM Do YYYY, h:mm:ss a format, which will output something like The date is Tuesday, December 10th 2022, 5:15:30 pm. In the third example, the date helper is used to format the date variable using the YYYY-MM-DD format, which will output something like The date is 2022-12-10.
The filterKey helper is a function that you can use in your DocumentEngine templates to filter an array of objects based on a key and a comparison operation. It uses the is helper to perform the comparison.
To use the filterKey helper, you can include it in your template like this:
{{#each (filterKey array key op value) as |item|}} <p>{{item}}</p> {{/each}}This example outputs a <p> element for each item in the filtered array.
The filterKey helper takes four arguments:
array: The array to be filtered. This should be an array of objects.key: The key to use for the comparison. This can be a string representing a property of the objects in the array.op: The comparison operator to use. This can be any valid operator that the is helper supports.value: The value to compare the object's property to.The getKey helper is a function that you can use in your DocumentEngine templates to get an array of values from a specific key in an array of objects.
To use the getKey helper, you can include it in your template like this:
{{#each (getKey array key) as |value|}} <p>{{value}}</p> {{/each}}This example outputs a <p> element for each value in the array.
The getKey helper takes two arguments:
array: The array to get values from. This should be an array of objects.key: The key to get the value from. This can be a string representing a property of the objects in the array.The count helper is a function that you can use in your DocumentEngine templates to count the number of items in a list.
To use the count helper, you can include it in your template like this:
<p>The count is {{count item1 item2 item3 ...}}.</p>This example outputs a <p> element containing the count of the items.
The count helper takes any number of arguments, each of which should be an item you want to count.
Here are some examples of how you might use the count helper in your templates:
<p>The count is {{count 'apple' 'banana' 'cherry'}}.</p>In this example, the count helper is used to count the number of items in the list 'apple', 'banana', 'cherry', which will output something like The count is 3.
The sum helper is a function that you can use in your DocumentEngine templates to calculate the sum of a list of numbers.
To use the sum helper, you can include it in your template like this:
<p>The sum is {{sum number1 number2 number3 ...}}.</p>This example outputs a <p> element containing the sum of the numbers.
The sum helper takes any number of arguments, each of which should be a number or a string that can be parsed as a number.
Here are some examples of how you might use the sum helper in your templates:
<p>The sum is {{sum 1 2 3 4 5}}.</p>In this example, the sum helper is used to calculate the sum of the numbers 1, 2, 3, 4, and 5, which will output something like The sum is 15.
The avg helper is a function that you can use in your DocumentEngine templates to calculate the average of a list of numbers.
To use the avg helper, you can include it in your template like this:
<p>The average is {{avg number1 number2 number3 ...}}.</p>This example outputs a <p> element containing the average of the numbers.
The avg helper takes any number of arguments, each of which should be a number or a string that can be parsed as a number.
Here are some examples of how you might use the avg helper in your templates:
<p>The average is {{avg 1 2 3 4 5}}.</p>In this example, the avg helper is used to calculate the average of the numbers 1, 2, 3, 4, and 5, which will output something like The average is 3.
The median helper is a function that you can use in your DocumentEngine templates to calculate the median of a list of numbers.
To use the median helper, you can include it in your template like this:
<p>The median is {{median number1 number2 number3 ...}}.</p>This example outputs a <p> element containing the median of the numbers.
The median helper takes any number of arguments, each of which should be a number or a string that can be parsed as a number.
Here are some examples of how you might use the median helper in your templates:
<p>The median is {{median 1 2 3 4 5}}.</p>In this example, the median helper is used to calculate the median of the numbers 1, 2, 3, 4, and 5, which will output something like The median is 3.
The list helper is a function that you can use in your DocumentEngine templates to create an array from the provided arguments and return a string representation of this array.
To use the list helper, you can include it in your template like this:
{{list item1 item2 item3 ...}}
This example uses the list helper to create an array from its arguments. The helper then joins these items into a string, separated by commas, for display purposes.
The list helper can take any number of arguments:
item1, item2, item3, ...: Each item represents a value to be included in the list. You can pass as many items as you need, and they will be concatenated into an array by the helper.Here is a practical example of using the list helper within a Handlebars template:
{{list 'Apple' 'Banana' 'Cherry'}}
In this example, the list helper takes three string arguments ('Apple', 'Banana', 'Cherry') and returns the list "Apple, Banana, Cherry".
The multiline helper is a function that can be used in your DocumentEngine templates to preserve newlines.
To use the multiline helper, include it in your template like this:
<p>{{multiline textVariable}}</p>This example outputs a <p> element where the newlines in textVariable are preserved.
Here are some examples of how you might use the multiline helper in your templates:
<p>{{multiline 'Line 1\nLine 2\nLine 3'}}</p>In this example, the multiline helper is used to preserve the newlines between 'Line 1', 'Line 2', and 'Line 3', which will output each line on a new line.
The markdown helper is a function that allows you to use Markdown syntax in your DocumentEngine templates.
To use the markdown helper, include it in your template like this:
<p>{{markdown markdownVariable}}</p>This example shows how you can output a <p> element that renders the Markdown content in markdownVariable as HTML.
Here are some examples of how you might use the markdown helper in your templates:
<div>{{markdown '# Heading\n\nThis is a **bold** text'}}</div>In this example, the markdown helper is used to render Markdown syntax. It would render a heading and a bold text.
The barchart helper is a function that creates a bar chart.
To use the barchart helper, include it in your template like this:
<div>{{barchart chartData [options]F}}</div>This example shows how you can output a <div> element that contains a bar chart representing the data in chartData.
Example data for the barchart helper:
{"chartData":
[{"key": "a", "value": 1}, {"key": "b", "value": 2},
{"key": "c", "value": 1}, {"key": "d", "value": 2},
{"key": "e", "value": 1}, {"key": "f", "value": 2}]}
Here's how you might use the barchart helper in your templates with the provided data:
<div>{{barchart chartData width=800}}</div>The barchart helper accepts several options to customize the appearance and behavior of the bar chart.
width: Specifies the width of the chart.height: Specifies the height of the chart.margin: Defines the margins around the chart.barColor: Sets the color of the bars in the chart.labels: Object containing labels for the x-axis and y-axis.The linechart helper is a function that creates a line chart.
To use the linechart helper, include it in your template like this:
<div>{{linechart chartData [options]}}</div>This example shows how you can output a <div> element that contains a line chart representing the data in chartData.
Example data for the linechart helper:
{"chartData":
[{"key": 1, "value": 1}, {"key": 2, "value": 2},
{"key": 3, "value": 1}, {"key": 4, "value": 2},
{"key": 5, "value": 1}, {"key": 6, "value": 2}]}
Here's how you might use the linechart helper in your templates with the provided data:
<div>{{linechart chartData width=800}}</div>Here's how you might use the linechart helper in your templates with the provided data:
<div>{{linechart chartData width=800 isCurve=false}}</div>The linechart helper provides various options to tailor the line chart.
width: Sets the width of the chart.height: Sets the height of the chart.margin: Determines the chart's margins.lineWidth: Defines the thickness of the line.lineColor: Specifies the color of the line.lineColors: An array of colors for multiple lines.isCurve: Determines if the line should be curved.tickSize: Size of the ticks on the axes.tickPadding: Padding around the ticks on the axes.The piechart helper is a function that creates a pie chart.
To use the piechart helper, include it in your template like this:
<div>{{piechart chartData [options]}}</div>This example shows how you can output a <div> element that contains a pie chart representing the data in chartData.
Example data for the piechart helper:
{"chartData":
[{"key": "a", "value": 1}, {"key": "b", "value": 2},
{"key": "c", "value": 1}, {"key": "d", "value": 2},
{"key": "e", "value": 1}, {"key": "f", "value": 2}],
"colors": ["DeepSkyBlue","White"]}
Here's how you might use the piechart helper in your templates with the provided data and color options:
<div>{{piechart chartData radius=200 width=400 height=400 colorRange=colors}}</div>The piechart helper offers a range of options for customizing the pie chart.
width: Determines the width of the chart.height: Determines the height of the chart.colorRange: Array of two colors defining the color range for the pie slices.radius: Sets the radius of the pie chart.The qrcode helper is a function that creates a qrcode.
To use the qrcode helper, include it in your template like this:
<div>{{qrcode text [options]}}</div>Here's how you might use the qrcode helper in your templates with the provided data and size options:
<div>{{qrcode 'www.youtube.com/watch?v=dQw4w9WgXcQ' size=200}}</div>The qrcode helper offers a range of options for customizing the pie chart.
size: Determines the size of the qrcode. If omitted the qr is full sized and needs a style with a sizeThe following @data variables are implemented by DocumentEngine.
Initial context with which the template was executed.
{{#each array}} {{@root.foo}} {{/each}}
Unless explicitly modified, this value is consistent across all portions of the page rendering, meaning it can be used within partials where depthed parameters are unable to reference their parent templates.
Set to true by the each helper for the first step of iteration.
{{#each array}} {{#if @first}} First! {{/if}} {{/each}}
Zero-based index for the current iteration step. Set by the each helper.
{{#each array}} {{@index}} {{/each}}
Key name for the current iteration step. Set by the each helper when iterating over objects.
{{#each array}} {{@key}} {{/each}}
Set to true by the each helper for the last step of iteration.
{{#each array}} {{#if @last}} Last :( {{/if}} {{/each}}