Template specifications
In most cases, templates do have a PROCESS section, only. Templates may have, however, also a VARIABLE section. ON_ERROR and FINAL sections are not supported for templates.
ASCII and HTML templates can be defined as shown in the example below
Note, that an HTML template must not contain the </process> sequence as fixed text in the process section, since this will terminate the process section. This problem can easily be solved by calling a separate ASCII template, which just produces the </process> sequence or by using > instead of > and < instead of <.
In generel, it is suggested to use ASCII templates rather than HTML templates.
// ASCII template
$template string Test()$
$VARIABLES$
int count = 0;
$PROCESS$
... template text
$END$
// HTML template
HTML templates look a little bit different like:
<template>
<header> string Test() </header>
<variables>
int count = 0;
</variables>
<process>
... template text
</process>
</template>
Template text (fixed text) can be entered in the template body (process section). Template text contains fixed text and embedded code.
Fixed text to be displayed in the template output is any sequence of characters (including fill characters as blanks or line breaks) except sequences enclosed in $...$, which are called embedded code. There are three types of embedded code expressions.
Output expressions are operands (usually database property names), which are enclosed between $...$ (see example). Thus, one may enter template call for other templates or operations of any complexity in an output expression, but no statements terminated by semicolon.
The content of an output expression is directly written to the target string. In an HTML environment, it is converted to HTML before.
$first_name$
$responsible(0).first_name$
$responsible(0).first_name + ' ' + responsible(0).second_name$
Embedded code does not directly create output, but is executed as expression code. Embedded code must be enclosed into ${...}$ (see example below).
Since code may contain WriteResult calls, code may also add data to the template result. This is one way to suppress HTML conversion for special texts, which have already HTML format.
Within embedded code one may refer to template variables defined in the variable section, to object variables, parameters and global variables like in an ordinary function.
${
while ( messages.next )
WriteResult(message.text,false); // no HTML conversion
}$
Control sequences are special expressions to control the text generation. Control sequences work similarly to the corresponding function constructs.
The return sequence is required, when the template is going to return a value as defined in the template header. The operand for the return value defines the value returned to the caller. No more text is generated after the return has been executed.
$return operand$
The if sequence defines a feature for conditional template generation: The else block is optional, but the $end$ must be defined in any case. Note that line breaks after the condition become part of the fixed text and lead to line breaks in the template result. Thus, sometimes line breaks must not be inserted:
// each line creates a line break
$if condition$
Text generated when condition is true
$else$
Text generated when condition is false
$end$
// conditional text without line break
$if sex == 'male'$Mr. $else$Mrs. $end$
The switch block is an enhanced feature for conditional processing, since it allows defining any number of processing path. In contrast to function switch, template switch provides alternatives and does not support a default block. As well as for if-else, the end statement is mandatory.
In order to handle other (or default cases), the switch block may contain a default statement. The default statement is mandatory.
// switch by constants
$switch ( hair_color )$
$case 'blue'$
Blue is not an accepted hair color. Use \'other\', instead.
$case 'yellow'$
Yellow is not an accepted hair color. Use \'other\', instead.
$default$
$hair_color§ is a valid value
$end$
// switch by operands
$switch condition$
$case operand$
Text generated when the case operand matches the switch
$case operand$
Text generated when the case operand matches the switch
$default$
Text generated for other cases
$end$
While and for allow defining loops over arrays or collections. Similar to the conditional processing, an end statement is required in any case. One may also insert embedded code to change the condition: The same way one may define for-loops according to the for-syntax defined for OSI functions.
// simple while loop
$while messages.next $
Message is: $messages.text$
$end$
// increase loop count within expression
${ rcount = 0; }$
$while rcount < 10 $
Number is: $rcount$
${ ++rcount; }$
$end$
// for loop
$for rcount = 0; rcount < 10; ++rcount $
Number is: $rcount$
$end$
In order to embed code within an OSI template one may use ${ statements }$ constructs. Each statement within the expression has to be terminated by semicolon (also single statements). in contrast to variable or operation path references ( $operation$ ), which add the (return) value to the template result, embedded code does not add anything to the template result string (except when calling WriteResult() within embedded code).
// embedded code
${
ph.next;
++rcount;
}$