Template Command Language
The template language consists of the following seven commands. When a template is processed, all of the commands in the template will be replaced with the appropriate values from the data dictionary used to process it. Click on a command name to see it's description.
Several of the commands are containers. Nesting of commands, to any reasonable depth, inside the content area of container commands is allowed.
All template commands are contained within square brackets ('[' and ']'). If you need a left bracket to appear in the final document enter '[[]' (left bracket, left bracket, right bracket) and if you need a right bracket to appear in the final document enter '[]]' (left bracket, right bracket, right bracket).
In the descriptions below, text inside '<' and '>' represent fields that you should replace with an appropriate value, removing the '<' and '>'. e.g. <put your value here>
Text inside '{' and '}' represents optional text. The braces should not be placed in the actual template file.
Many of the commands use data keys. Keys must start with a letter and not contain spaces, but may contain letters, numbers, and underscores. Keys may also be strung together with periods (person.first_name). This is called a compound key and is used when parts of the data dictionary are a tree rather than a flat list of values.
comment -- [comment <comment text>]
The comment command allows you to place information in the template that you do not want copied to the final document. The command and all it's comment text will be removed during processing.
The <comment text> may contain contain spaces.
date -- [date {<date format>}]
The date command puts out the current date. <date format> is a description of the format to print the date. If no format is given, the format "%a %m/%d/%y %I:%M:%S %p" is used. Following is a description of the date conversion specifiers:
| Specifier | Description |
%% |
a '%' character |
%a |
abbreviated weekday name |
%A |
full weekday name |
%b |
abbreviated month name |
%B |
full month name |
%c |
shorthand for "%X %x",
the locale format for date and time |
%d |
day of the month as a decimal number (01-31) |
%e |
same as %d but
does not print the leading 0 for days 1 through 9 |
%F |
milliseconds as a decimal number (000-999) |
%H |
hour based on a 24-hour clock as a decimal number (00-23) |
%I |
hour based on a 12-hour clock as a decimal number (01-12) |
%j |
day of the year as a decimal number (001-366) |
%m |
month as a decimal number (01-12) |
%M |
minute as a decimal number (00-59) |
%p |
AM/PM designation for the locale |
%S |
second as a decimal number (00-59) |
%w |
weekday as a decimal number (0-6), where Sunday is 0 |
%x |
date using the date representation for the locale |
%X |
time using the time representation for the locale |
%y |
year without century (00-99) |
%Y |
year with century (such as 1990) |
%Z |
time zone name (such as Pacific Daylight Time) |
%z |
time zone offset in hours and minutes from GMT (HHMM) |
datevalue -- [datevalue <date value key> {<date format>}]
The datevalue command gets replaced by the value in the data dictionary represented by <date value key>. The value must be a date object. If no format is given, the format "%a %m/%d/%y %I:%M:%S %p" is used. Use the same format conversion specifiers as described above in the date command.
each -- [each <each id> <each value name> <list key>]<content area>[endeach <each id>]
The each command repeats a section of the template once for each value in a list. Inside <content area> the data key <each value name> will contain one value from the list referenced by <list key>. In addition, <each value name>_index will have the index of the value in the list, starting at zero. <each id> is any unique identifier to match the [each with it's [endeach command.
if -- [if <if id> <left test value> <test> <right test value>]<true content area>{[else <if id>]<false content area>}[endif <if id>]
The if command includes or excludes a section of the template based on a test. <left test value> must be a key in the data dictionary, <right test value> can be either a literal value (without spaces) or a key in the data dictionary. If both test values are integers, a numerical comparison is done, otherwise a string comparison is done. <test> must be one of the tests listed below. <if id> is any unique identifier to match the [if with it's [else and [endif commands. the [else <if id>]<false content area> portion is optional. If the test is true, the <true content area> will be included. If the test is false, the <false content area> with be included if present.
| Test | Description |
| == | true if left is equal to right |
| != | true if left is not equal to right |
| < | true if left is less than right |
| > | true if left is greater than right |
| <= | true if left is less than or equal to right |
| >= | true if left is greater than or equal to right |
Alternate form -- [if <if id> <test> <test value>]<true content area>{[else <if id>]<false content area>}[endif <if id>]
The if command includes or excludes a section of the template based on a test. <test value> must be a key in the data dictionary. <test> must be one of the tests listed below. <if id> is any unique identifier to match the [if with it's [else and [endif commands. the [else <if id>]<false content area> portion is optional. If the test is true, the <true content area> will be included. If the test is false, the <false content area> with be included if present.
| Test | Description |
| -s | true if <test value> is in the data dictionary |
| -ns | true if <test value> is not in the data dictionary |
include -- [include <file to include>]
The include command inserts the contents of another file into the template. The contents of the file are parsed for template commands. <file to include> must be a full path to the file to include.
loop -- [loop <loop id> <loop value name> <start value> <end value> <value increment>]<content area>[endloop <loop id>]
The loop command repeats a section of the template a specific number of times. <start value>, <end value>, and <value increment> can either be integers or value keys that hold integers. The loop will repeat from the start to the end values stepping my the increment. Inside <content area>, the data key <loop value name> will be defined and will have the current value of the loop. <loop id> is any unique identifier to match the [loop with it's [endloop command.
For Example: [loop loop1 loop1value 1 8 2][loop1value] [endloop loop1] would output 1 3 5 7
set -- [set <value key> <expression>]
The set command allows you to set a value in the data dictionary while the template is being processed. The entry for <value key> will be set to <expression>. The expression can be any of the following:
value -- [{value} <value key>]
The value command gets replaced by the value in the data dictionary represented by <value key>.The value command name is optional.
Template language version 1.1