C Template Library 1.0


TMPL1 DLL Function and Usage

The C Template Library 1.0 is a template expander library and is similar to the perl HTML::Template module. Input to the expander is a template file, a variable list, and an optional format function list. The expander processes the template using the variables in the variable list, and outputs the result. This DLL makes the powerful templating technology available for Xbase++. There is a easy to use object oriented API interface available. This API-Implementation is further called tmpl1.

Introduction

Using templates makes it easier to separate information (the variable list) from the presentation (the template file and format functions). You can construct a variable list that can be output in a variety of formats or languages, using different templates. The template language is simple, but powerful enough for you to design flexible templates that handle many different situations. The C Template library is fast and efficient because it is written in C, and the API is easy to use.

Author: Stephen C. Losen, University of Virginia

Template Files

A template file consists of text sequences, template tags and comments. Text sequences are copied to the output. Template tags are removed from the input, processed, and the result is output. Comments are removed from the input and do not appear in the output.

The template language supports these features:

Text Sequences

A text sequence is any sequence of characters that is not a template tag and not a comment. A text sequence is copied unchanged to the output with a few exceptions. You can use a backslash (\) to suppress outputting a line terminator. A single \ at the end of a line is not output and neither is the line terminator. You can escape this behavior with two backslashes (\\) at the end of a line, which is output as a single \ followed by the line terminator. Any other \ is copied unchanged to the output.

Comments

Any text (including template tags and line terminators) enclosed by <* and *> is a comment, which the expander does not output. Comments cannot be nested. Within a comment <* is ignored and the comment ends at the first *> A *> without a preceding <* is considered ordinary text. A <* without a following *> is an error. Template tags may not contain comments because inserting a comment into a tag splits it into ordinary text sequences. If your template needs to output a literal <*, you can split < and * with a short comment like this: <<**>*.

You are certainly free to use comments supported by whatever language that your template outputs. For example, you can use HTML comments such as <!-- this is a comment -->. The template expander treats this as ordinary text and copies it to the output.

Template Tags

The template language has the following tags.

<TMPL_VAR name="varname" default="value" fmt="fmtname">
Variable substitution. The tag is replaced in the output with the value of the variable named varname. If varname does not exist, then the tag disappears in the output, unless you specify a default value to output with the optional default="value" attribute. If varname exists, but has a null value (""), then the null value is output.

Usually the value is output without modification. The optional fmt="fmtname" attribute specifies a format function that the expander calls to output the value with appropriate formatting or encoding. The format function is also called when a tag's default value is output.

<TMPL_IF name="varname" value="testvalue">
Introduces an if statement. The value="testvalue" attribute is optional. The tag evaluates to true or false as follows:
<TMPL_IF name="varname">
is true if variable varname exists and has a non-null value, otherwise false. You can also use this to test for the existence of a loop variable.
<TMPL_IF name="varname" value="testvalue">
is true if variable varname exists and has the value testvalue, otherwise false.
<TMPL_IF name="varname" value="">
is true if variable varname does not exist or has a null value, otherwise false. You can also use this to test for the non-existence of a loop variable.
<TMPL_ELSIF name="varname" value="testvalue">
A component of an if statement. The value="testvalue" attribute is optional. The TMPL_ELSIF tag evaluates to true or false using the same rules as the TMPL_IF tag.
<TMPL_ELSE>
A component of an if statement.
</TMPL_IF>
Terminates an if statement.
<TMPL_LOOP name="loopname">
Introduces a loop statement where loopname is the name of a loop variable, which is a list of variable lists.
<TMPL_BREAK level=N>
Loop break. This tag must always be inside of a loop statement. It causes the current iteration of the loop statement to stop and processing resumes immediately after the loop statement. By default TMPL_BREAK breaks out of the closest surrounding loop statement, whose nesting level is one. The optional level=N attribute, where N is a number greater than zero, can be used to specify a loop statement at a higher nesting level, i.e., a loop statement that surrounds the closest surrounding loop statement.
<TMPL_CONTINUE level=N>
Loop continue. This tag must always be inside of a loop statement. It causes the current iteration of the loop statement to stop and processing resumes at the beginning of the next loop iteration. By default the TMPL_CONTINUE tag operates on the closest surrounding loop statement and the optional level=N attribute has the same purpose as in the TMPL_BREAK tag.
</TMPL_LOOP>
Terminates a loop statement.
<TMPL_INCLUDE name="filename">
File inclusion. The tag is replaced with the contents of template file filename and the result is expanded. The included file must be a syntactically correct and complete template. For example, you cannot have a TMPL_IF tag in one file and have its corresponding </TMPL_IF> in another file. However, you can place TMPL_INCLUDE tags inside of if statements or inside of loop statements. The included file is not actually opened and processed until the flow of control reaches the TMPL_INCLUDE tag. An included file may include other files, which may also include files, up to a depth of thirty. Exceeding this limit is an error and probably indicates a cycle where a file includes itself either directly or indirectly.

If filename begins with .../ then ... is replaced with the directory name of the enclosing template filename. If there is no directory name (no slash) then the .../ is removed. For example, if the enclosing file is dir/templates/main.tmpl and filename is .../include/incl1.tmpl, then the result is dir/templates/include/incl1.tmpl.

Template tag syntax has these features.

The If Statement

The syntax of the if statement is

<TMPL_IF name="varname" value="testvalue">
template-list
<TMPL_ELSIF name="varname" value="testvalue">
template-list
<TMPL_ELSE>
template-list
</TMPL_IF>

A template-list is any sequence (including an empty sequence) of comments, text sequences, template tags, if statements, or loop statements. One TMPL_IF tag is required and must come first. There can be zero or more TMPL_ELSIF tags and zero or one <TMPL_ELSE>, which must come after any TMPL_ELSIF tags. The final </TMPL_IF> is always required. Any other use of these tags is an error.

Zero or one of the template-lists in an if statement is expanded and the rest of the if statement disappears. The TMPL_IF and TMPL_ELSIF tags are evaluated in order until a tag evaluates to true. Then the template-list immediately following the true tag is expanded. If no tags are true then the template-list after the <TMPL_ELSE> is expanded. Since the <TMPL_ELSE> is optional, possibly no template-lists are expanded and the entire if statement disappears.

The if statement syntax shown above is formatted for readability. You can format if statements any way you want, such as putting an entire if statement on one line. The same is true for loop statements.

The Loop Statement

The syntax of the loop statement is

<TMPL_LOOP name="loopname">
template-list
</TMPL_LOOP>

Any other use of these tags is an error. Loopname is the name of a loop variable, which is a list of variable lists. Each variable list is essentially a row of data. If loopname does not exist, then the loop statement silently disappears. Otherwise the template-list is expanded repeatedly, one time for each variable list (row) in loopname. Within the template-list you can refer to variables in loopname's current variable list and refer to variables in enclosing variable lists, such as the variable list that contains loopname. A variable in an inner list overrides a variable with the same name in an enclosing list.

Within a loop statement you can use the TMPL_BREAK tag to break out of the loop and resume processing immediately after the loop statement. Or you can use the TMPL_CONTINUE tag to skip the rest of the current loop iteration and resume at the beginning of the next iteration.

TMPL1 DLL API

Object oriented API

cReport()

Class for tmpl1.

class methods

:new( <sReportpath> ) Creates an instance of the cReport class. The parameter <sReportpath> is the path to the template file, to which a ".rpt" suffix is added. The template files should also reside in the programs deployment path. The cReport class is a child of DataObject. Therefore arbitrary instance variables can be created simply by assigning a value. These variables act as the variables for the template engine. When a character string is assigned, this value is used for variable substitution, the instance variable name is the template variable name, the value is the substitution string. When an array of strings is assigned, these values form a loop variable with the constant name "var1". See the example for clarification.

:render() expands the <sReportpath> template file with the rules of the template language and returns the expanded template file in a character variable.

:version() Returns the used TMPL1 version as a string.

Example

order.ps.rpt:
Hello <TMPL_VAR name="you" fmt="entity">!
<TMPL_LOOP name="l1">\
  from <TMPL_VAR name="var1">!
</TMPL_LOOP>\

example.prg:
  #pragma library( "tmpl1.lib" )
  oTemplate := cReport():new( "order.ps" )
  oTemplate:you := "Jake"
  oTemplate:l1 := { "Betty", "Jane", "Mike" }
  sExpanded := oTemplate:render()

this prg will store the following string in sExpanded:
Hello Jake!
  from Betty!
  from Jane!
  from Mike!

Deployment

Files

tmpl1.dll The DLL with the tmpl1-routines from http://libctemplate.sourceforge.net/. This file must be installed in <Alaska 2.0 base directory>\xpp20\lib, <Alaska 2.0 base directory> usually is "C:\Program Files\Alaska Software". This file also must be delivered along with the applications runtime dlls as described in Xbase++ docs "Deployment of Xbase++ applications": "For simplicity, an Xbase++ application should be deployed with all the runtime files contained in the xpp<xx>\runtime folder". This file contains the GPL3-licensed code from libctemplate.sourceforge.net and can be freely distributed.

tmpl1.lib The import library is needed by the Xbase++-linker ALINK.EXE and should be also installed in <Alaska 2.0 base directory>\xpp20\lib. This file is only needed at link-time.

tmpl1.obj This is the C-API-interface from Xbase to tmpl1 and is needed by the Xbase++-linker to include into the application. It should be copied into the project-directory and added to the projects target with "Add existing file ...". Since it is included in the application this file is only needed at link-time of the application.

Copyright

The interface tmpl1.obj is Copyright Axel Reinhold
The library tmpl1.dll contains TMPL1 from http://libctemplate.sourceforge.net/ with GPL3 license.

Demo version

The Demoversion <arxtmpl1d.10.x.y.z-x86.zip> returns only 400 expansions. After that empty expansions are always returned. Ask for a unlimited licensed version of tmpl1 by mail to axel@toarx.de.

Disclaimer

This interface library is supplied without any warranties of any kind, and you use it entirely at your own risk.

Note: Advanced Web 2.0 hosting small with power

Menü