Template commands

Template commands are always enclosed in braces like {this}. No whitespace is permitted between the opening brace and the command; no line break may occur within the braces. Commands and their attributes are case-sensitive. Most template commands contain one or more expressions; basic expressions are data field references and simple literal values. See the Expression reference chapter for more information.

{open}

{open dbdfile as filehandle}

{open customers.dbd as CustomerDatabase}

Prepares a database for further access in this template and assigns a user-defined, arbitary symbol name, a database file handle, to it. Note that the database definition file is specified in the open command, not the database file itself. The given file specification is interpreted relatively to the path where the template file resides.

{select}

{select recordvar in filehandle [where condition] [sort sortkey]}

{select AllCustomers in CustomerDatabase}
{select LatestCustomers in CustomerDatabase where record.createdate > date - 7}
{select SortedCustomers in CustomerDatabase sort record.lastname then record.firstname}

Selects all or a range of records from the database given through its handle filehandle that had been assigned to it through the open command and optionally sorts them. The selected records are placed in the recordvar array.

Specify an expression as condition to restrict the selection to those records for which the given expression evaluates to a logically true value. The expression given as sortkey specifies the sort key by which the records are sorted before being written to the recordvar array. In both condition and sortkey the record special variable represents the record that is currently examined.

Internally, {select} iterates over every record in the database and evaluates condition, temporarily pointing the special variable record to the record that has just been read. If the subsequent evaluation of condition yields a logically true result, the respective record is included in the recordvar array. The sortkey expression is handled similarly for each selected record.

See the Sort key operators chapter on how to create complex sorting criteria.

{insert}

{insert expression}

Our company currently has {insert count AllCustomers} customers total.

Inserts the specified expression at this point. Only scalar values can be inserted; arrays and hashes are not supported by {insert} for immediate inclusion. (You can of course always insert a given single element of an array or a hash, though; see {foreach} below.)

{foreach}

{foreach loopvar in list}
{/foreach}

Customer listing:
{foreach Customer in SortedCustomers}
  {insert Customer.lastname.content}, {insert Customer.firstname.content}
{/foreach}

Executes the template block enclosed by {foreach} and {/foreach} once for each element of the given list. The list can be either an array (like the recordvar array filled by the {select} command), a hash or a scalar expression which is handled like a single-element list. Inside the {foreach} block, loopvar represents the currently examined list element.

Note that although loopvar cannot be used to change the corresponding element of list, the list elements' subelements (if the list happens to be made of hashes or nested arrays) can be modified through it. You can use the first, last and index operators on loopvar to easily determine whether the loop is in its first or last iteration and which element is currently being examined. See the Loop variable operators chapter for details.

{if} and {else}

{if condition}{/if}
{else}{/else}

Customer {insert Customer.lastname.content} signed up
{if Customer.createdate > date - 7}
  within the last week.
{/if}
{else}
  more than one week ago.
{/else}

Executes the template block enclosed by {if} and {/if} only if the given condition evaluates to a value that is logically true. The following optional {else} command executes the template block enclosed by {else} and {/else} only if the previous {if} condition evaluated to false. Text may appear between {/if} and {else}.

{for}

{for loopvar [from startval] to endval [step stepval]}
{/for}

Print all numbers from 1 to 10: {for Number to 10}{insert Number} {/for}
Print the numbers 15, 10 and 5: {for Number from 15 to 5 step -5}{insert Number} {/for}

Executes the template block enclosed by {for} and {/for} once for each value that lies between startval (or 1 if no start value is given) and endval. The loopvar represents the current value inside the enclosed template block. After each iteration, loopvar is incremented by the value of stepval (or by 1 if no stepping value is given).

{set}

{set var to expression}

{set CustomerCount to count AllCustomers}
{set Customer[CustomerCount - 1].lastname.content to "Buschbeck"}

Sets the given variable var to the result of the specified expression. The var can be arbitarily complex as long as it results in a variable lookup (for instance an array element whose index is calculated through a complex expression).

{sort}

{sort array [by sortkey]}

{sort AllCustomers by numeric item.createdate}

Sorts the given array by the specified sort key (or alphanumerically if no sortkey is given). Note that only arrays can be sorted (as filled by {select}, for instance). In sortkey the item special variable represents the currently examined array element. See the Sort key operators chapter on how to create complex sorting criteria.

{index}

{index array by indexkey}

Creates a hash from an array, using the results of the given indexkey expression as hash keys. In indexkey the item special variable represents the currently processed array element.

The {index} command is useful for creating lookup tables in order to efficiently emulate relational databases. For example, imagine a database customers.dbd that contains all customer details and a second database orders.dbd that contains their orders, with both databases being connected through the customers' id and the orders' user-defined customerid field:

{open customers.dbd as CustomerDatabase}
{select Customers from CustomerDatabase}

{open orders.dbd as OrderDatabase}
{select Orders from OrderDatabase}

{# Create a customer lookup table indexed by customer id #}
{index Customers by item.id}

{# Output all dates of order together with the customers' names #}
{foreach Order in Orders}
  Customer: {insert Customers[Order.customerid].lastname}
  Date of order: {insert Order.createdate}
{/foreach}

Note that this could have been more easily achieved by embedding the customers' orders as an array into the customer records themselves, though; see also the What is xmlbase? chapter.