Templates

What templates are

Templates are a feature, that allows the user to customize the text output of the device in certain scenarios.

Currently templates are available for customizing the text content of these notification channels:

• Email (Docs page)
• Webhooks (Docs page)

info

Default template files are provided and can be selected to use on the configuration pages of the respective interfaces (Email, Webhooks, ...).

Additionally custom templates can be added and edited on the device. Please refer to the Managing Templates section for further details.

warning

Templates are an advanced feature, that require basic technical skills. Please refer to an IT professional or consult egnite for additional services.

Terms used in this reference

Term	Meaning
web variable, variable	A dynamical value that can be output or used in expressions. See Simple Web variables
table	An iterable array-like structure containing variables. See Web variable Tables, The for Command and The use Command
literal	A value that can be defined directly inline and output or used in expressions
exp	Expression, consisting of operands (variable, literal, return values) and operators

info

Boolean values true and false are expressed as digits 1and 0 in the template language.

The egnite Template Language

In essence, templates are text files that get processed by the template engine on the device. The result of this processing is again text.

The contents of a template (input) can consist of

• static text, that gets output by the template engine as is
• placeholders, denoted by curly braces { and }, that get replaced by the template engine

How exactly placeholders get replaced, depends on the type of placeholder and sometimes additional parameters.

Basically there are two types of placeholders, that will be explained further in the following:

• Output placeholders
• Command placeholders

Both of those can use expressions, to define their corresponding output.

Expressions & Operations

Literal Values

12345	Constant number
'abc' or "abc"	Constant string
true or false	Boolean constant

Arithmetic Operations

exp1 + exp2	Addition
exp1 - exp2	Subtraction
exp1 * exp2	Multiplication
exp1 / exp2	Division
exp1 % exp2	Remainder / Modulus

Bitwise Operations

exp1 & exp2	Bitwise AND
exp1 | exp2	Bitwise OR
exp1 ^ exp2	Bitwise XOR
exp1 >> exp2	Shifts bits in exp1 right by exp2 bits
exp1 << exp2	Shifts bits in exp1 left by exp2 bits

Logical Operations / Comparisons

info

The return values of these operations are either 1 (true) or 0 (false)

exp1 == exp2	Result is 1, if exp1 equals exp2.
exp1 != exp2	Result is 1, if exp1 is unequal to exp2.
exp1 < exp2	Result is 1, if exp1 is smaller than exp2.
exp1 <= exp2	Result is 1, if exp1 is smaller than or equals exp2.
exp1 > exp2	Result is 1, if exp1 is larger than exp2.
exp1 >= exp2	Result is 1, if exp1 is larger than or equals exp2.
var in table	Result is 1, if table contains var

The results of comparisons can be linked logically:

exp1 and exp2	Result is 1, if both expression exp1 and expression exp2 are not zero.
exp1 or exp2	Result is 1, if either expression exp1 or expression exp2 is not

Finally, the following two unary operations can also be applied:

-var	Mathematical negation
!var	Logical negation

Operator precedence

The operations in combined expressions are listed in the following order:

1. Numeric and logic negations -a and !a.
2. Multiplications and divisions, a*b, a/b and a%b.
3. Addition and subtraction a+b and a-b, as well as bitwise operators a&b, a|b and a^b
4. Bit shift operators a<<b, a>>b
5. Comparisons a==b, a!=b, a<b, a<=b, a>b and a>=b
6. Logic operation a and b and a or b

The usual parentheses can be used to designate a sequence. Hence

-A * B + C == D and E

is identical to

((((-A) * B) + C) == D) and E

Output placeholders

Output placeholders or Outputs are enclosed by a pair of two curly braces

{{ Expression }}

Outputs get replaced by the template engine according to its content, as expressions, which can be

• Web variables and tables
  e.g {{fw_manufacturer}} outputs egnite
• Literal values
  e.g {{"hello world"}} outputs hello world
• Arithmetic Operations
  e.g {{40 + 2}} outputs 42
• Logical Operations / Comparisonse
  e.g {{fw_manufacturer != "egnite"}} outputs 0, which stands for false
• Results of other (sub) expressions

Command placeholders

Command placeholders or Commands are enclosed by a pair of curly braces with percent signs:

{% Command %}

In contrast to output placeholders, commands dont get simply converted to a text output, but are a control structure, that equips the template language with features such as if/else statements or loops.

The following commands can currently be used:

Command	Description
if, elif, else, endif	Skips lines within a template file.
for, endfor	Repeats lines within a template file.
use, enduse	Selects elements of a table.
set	Sets variables.
escape	Automatically replaces certain characters.

The if Command

This command makes it possible to skip specific lines within a template file if certain conditions are fulfilled or not fulfilled.

{% if expression %}
...
{% endif %}

The expression can be any required template expression, which is then reduced to true or false. All lines between the if command and endif are ignored if the expression is false.

info

The expression does not necessarily need to be a comparison. A simple variable, for instance, can suffice.

Expression Value	Boolean Value
Only digits, with algebraic signs, if required	Only false if 0, otherwise always true
Contains at least a character or a special sign	Always true
Does not contain characters (empty string)	Always false

There are some additional commands that can only be used between if and endif:

{% elif expression %}
...
{% else %}

elif can be used repeatedly, else can only be used in a single instance. These commands are only executed if the preceding if command and all expressions of the preceding elif commands were false. Depending on the contents of the ip variables, the following example outputs the text localhost, broadcast or other as an HTML paragraph.

{% if ip == '127.0.0.1' %}
<p>localhost</p>
{% elif ip == '255.255.255.255' %}
<p>broadcast</p>
{% else %}
<p>other</p>
{% endif %}

The for Command

Multiple variables can be combined and organized in tables. A table of all sensors, for instance, might contain their respective names, thresholds and other parameters. The command for serves to execute loops for tables. The table's name needs to be entered after the command for. This will execute all lines between for and endfor for each element of the specified table. Within these lines, the values of individual elements of a table can be output. The following example creates a list of all sensors with their current values:

<ul>
{% for sensortab %}
<li>{{ sensortab_name }} {{ sensortab_value }}</li>
{% endfor %}
</ul>

By default, all elements of a table are iterated through. It is also possible to specify which part of a table should be used after the table name in square brackets. Three expressions are possible, separated by colons, which are evaluated to numbers. The first expression specifies the start index beginning at 0. The second expression specifies the end index, which itself is not included. The third expression controls the order, where only 1 for forward and -1 for backward are allowed. The following example outputs inputs 5, 6, 7, and 8:

{% for inputtab[4:8] %}
  {{ loop.index }}: {{ inputtab_name }} {{ inputtab_state }}<br>
{% endfor %}

In this example, note that the template itself starts counting at 0, while the output starts at 1.

All three expressions are optional. If they are missing, a default value is used for each.

It is also possible to use a negative index for the start or end to count from the end of the table

Also see Table expressions.

The use Command

This command is similar to the for command. However, the lines between use and enduse are only executed once for a certain index of a table. The following example will return the customer name in the fifth entry of a table of customers:

{% use sensortab[1] %}
<span>{{ sensortab_name }} {{ sensortab_value }}</span>
{% enduse %}

It is also possible to access a value of a specific line in a table by adding a period, followed by a 0-based index to the name of the variable. The example

{{sensortab_value.0}}

will return the most recent value of the first sensor.

Also see Table expressions.

The escape Command

In some file formats, some characters can hold specific meanings. They need to be replaced by a different text, in order to return these characters as regular text without these meanings. The escape command can achieve this automatically for certain formats. The escape type (see table below) comes after the escape keyword.

The following example will return the contact in a JSON document:

{%escape json%}
{
"contact": "{{syscontact}}"
}

The JSON document would be invalid, if the web variable syscontact contained the character ". Using the escape command replaces the " by \".

The escape command will execute the current replacements until the next occurence of the escape command or until the end of the template. An if command can also be used to skip the escape command. The following replacements can currently be used:

Escape Type	Description
none	No characters will be replaced.
json	The following escape sequences for JSON strings will be used: \n \r \t \\ \"
html	The symbols & < > " ' will be replaced by HTML entities.
url	URL encoding or percent encoding
identifier	Only ASCII digits, ASCII letters, and underscores are allowed ([a-zA-Z0-9_]). The first character must not be a number. All non-allowed characters are replaced by underscores, whereby a single underscore can replace multiple characters.

Comments

All characters between {# and #} including the braces are ignored. This can be used to add comments to the template. Example:

{# This is a comment #}

Omitting the End of a Line

Outputs, commands and comments can optionally include a – at the end. This omits all following spaces up to the end of the line, as well as the line break. Templates can thus be formatted to be more readable without superfluous lines in the output. Example:

{{syslocation-}}
{%if 1-%}
{%endif-%}
{#comment-#}

Functions

arg(argument)

The retrieval parameters of the template loader can be determined with the help of this function.

The parameter argument can either be a number that determines which GET parameter will be retrieved. Alternatively, the name of the GET parameter can be specified.

parsetime(text[, local])

Convert date and optionally time from text into a timestamp. If the optional parameter local is set and the text does not contain an explicit UTC offset, the local timezone is used.

concat(value...)

Concatenates multiple strings, that are passed as arguments.

setvarflag(name, value)

Sets a display setting for certain web variables. Currently available options are:

• invalid_null: Specifies that invalid values should be displayed as null. This is useful for JSON files to avoid syntax errors. Otherwise, invalid values are displayed as an empty string, which is preferable for CSV files.
• decimal_comma: Ensures that a comma is used instead of a period as the decimal separator in numbers.

tablefindtime(tablename, timestamp)

Searches the database for the table tablename, which can be histotab or changetab for an entry with a matching argument timestamp.

timerange(b, e, s)

Configures the histotab and changetab tables to aggregate values over specified time intervals.

Parameter	Description
b	Start timestamp. If <= 0, the value is added to the current time.
e	End timestamp. If <= 0, the value is added to the current time.
s	Step size in seconds. If <= 0, defaults to 60.

strftime(format[, ts[, local]])

Formats a timestamp using a format string.

The argument format contains the format string and supports a subset of the C strftime function. The optional argument ts is the timestamp; if omitted, the current time is used. If the optional argument local is present and non‑zero, the time is formatted in the local timezone.

Format specifier	Example	Description
%c	30.08.2022 12:34:56	Date and time in the configured format. Synonym for %x %X
%d	30	Day of the month
%F	2022-08-30	Synonym for %Y-%m-%d
%H	12	Hour of the day from 00 to 24
%j	242	Day of the year as a number
%m	08	Month as a number from 01 to 12
%M	34	Minute as a number from 00 to 59
%R	12:34	Synonym for %H:%M
%S	56	Second as a number from 00 to 59
%w	2	Day of the week as a number from 0 to 6, where Sunday is 0
%x	30.08.2022	Date in the configured format
%X	12:34:56	Time in the configured format (currently always %H:%M:%S)
%T	12:34:56	Time in the format %H:%M:%S
%Y	2022	Year as a number
%z	+0200	Offset from UTC
%:z	+02:00	Offset from UTC with ":" as separator
%%	%	Literal percent sign

Additionally, one of the following characters can be used after the percent sign to modify the format:

Character	Behavior
_	(underscore) Numbers are left-padded with spaces (not with zeros).
-	(hyphen) No padding is applied at the start of numbers.
0	(number zero) Numbers are left-padded with zeros (this is the default).

Web Variables

Web Variables can be either simple variables or iterable tables, that organize multiple variables in an array-like structure. Simple variables and table items have a data type, which is also denoted in the following list of available web variables.

Simple web variables

Simple web variables are referenced by their names. Example:

{{fw_manufacturer}}

is replaced by the string

egnite

Web variable Tables

Variables that are organized in tables can additionally include a (zero-based) index, separated by a period. Example:

{{sensortab_name.1}}

is replaced by the name of the second sensor.

The index 0, which can be omitted, is used for the first sensor. Both

{{sensortab_name.0}}

and

{{sensortab_name}}

will retrieve the name of the first sensor.

Table expressions

There are special expressions to evaluate the current index of a table iteration and the length of a table. These work inside the for command and the use command.

Variable	Description
loop.index0	Current index of the innermost loop starting at 0.
loop.index	Current index of the innermost loop starting at 1.
loop.length	Length of the table of the innermost loop.
sometable.index0	Current index of the innermost loop for table sometable starting at 0.
sometable.index	Current index of the innermost loop for table sometable starting at 1.
sometable.length	Length of the table sometable.

Variable data types

info

The type of variable specifies the possible range of values or the possible number of characters that can be used.

Type	Range / Length
bool	0 or 1
check	"checked" or empty string
int8	-128 to 127
uint8	0 to 255
int16	-32768 to 32767
uint16	0 to 65535
int32	-2147483648 to 2147483647
uint32	0 to 4294967295
fixed	Number with a fixed number of decimal places
char[x]	String with a maximal length of x
char[]	String of up to 128 characters
ts	Time stamp, seconds since 1/1/1970
date	Date in the configured format
time	Time in format hh:mm:ss
ip4	IP-Address in format 1.2.3.4

List of Available Web Variables

A complete list of all available web vars is available

• as a human readable docs page (Web Variables)
• as a machine readable .json file, suited for LLMs

Troubleshooting

//TODO

Line endings

Character encoding

Managing Templates

//TODO Screenshots

Custom Templates can be added, edited and deleted from within the web interface.

The central place for managing templates is the Firmware configuration page, which can be accessed from the main menu in the System section.

info

Additionally, editing a template can be done from the configuration page, where the template is being selected, such as the Email interface configuration page. Clicking on the Edit Button next to the template file selection dropdown will navigate to the same form, as the central method provides!

Overview of existing templates

1. Navigate to the Firmware configuration page, which can be accessed from the main menu in the System section.
2. Find the Files section.
3. You will find a table with installed files. Those files, that end with .tpl are the template files.

note

Template files exist internally within a File System and thus have a path associated with them, which is displayed in the overview table.

Adding templates

1. Navigate to the Firmware configuration page, which can be accessed from the main menu in the System section.
2. Find the Create/Edit file section.
3. Choose the appropriate path for the new template to be saved in. //TODO
4. Choose a unique file name.
5. Click the button.
6. A page with an editor form will open. Refer to Editing Templates for the next steps.

Editing templates

1. Navigate to the template editor form page by either
   

• Clicking on the Edit Button in the row of the template in the file overview table, or
• Clicking on the Edit Button next to the template selection dropdown on an interface configuration page, or
• Adding a new template

2. Optionally edit the Filename field
3. Paste or edit in place the contents of the template in the File contents field
4. Click the button, to save your edits and reload the page.
   A preview of the proccessed template output will be displayed below the editor form, for you to assess and debug your template code.
   Alternatively click the button, to save without showing a preview and return to the previous page.

Deleting templates

// TODO

Click on the Delete Button in the row of the template you want to delete in the file overview table

Examples

//TODO: Link or paste example template files