Template Documentation

The following is an extract from the documentation for the templating process. It describes the template constructs available for use by the template writers.

The TemplateNamed construct is used to refer to a named template. This class is used to retrieve the template by name when necessary. It may also be called directly when necessary. It treats the template-name as a file-name in the template-directory, unless a full file-name is given, beginning with a leading slash.

Currently, this class regards the name as referring to a file in which the template resides. This file is parsed by TemplateParser, but because that class is not public, here is the documentation on the format of the file:

The format of the file is arbitrary text, interspersed with template tags of the following format:

A slot to be replaced with data from the dynamic microdocuments:

    <?template slot 3 order.items>
                                                                  

    <?template slot 3 items oldName1 newName1 oldName2 newName2>
                                                                  

    <?template slot 3 items[0].price #BARE>
                                                                  

    <?template slot 3 items[0].price #QUOTE>
                                                                  

As above, but with strings url-encoded:

    <?template slot 3 items[0].price #URL>
                                                                  

Obtain the number of elements in a sequence:

    Your search returned <?template slot 1 results.#> result(s).
                                                                  

    <?template loop 0 results>
      arbitrary contents for each item in the result, in which the
      -1 refers to the current item being processed, and @ returns
      the index of the current item being processed:
      <?template slot -1 @> <?template slot -1 title>
    <?template /loop>
                                                                  

The loop actually supports lots of options:

    <?template loop 1 pages>
      ... stuff at beginning of loop ...
      <?template item>
        ... stuff for each iteration of the loop ...
      <?template separator>
        ... stuff to insert between each iteration ...
      <?template end>
        ... stuff after all the iterations ...
      <?template none>
        ... stuff if loop had no iterations
    <?template /loop>
                                                                  

Use the 'item' construct only if you want to have stuff at the beginning of the loop. Just omit it otherwise, then the stuff is just assumed to be the per-item output.

A named template inclusion, optionally relative to the enclosing template:

    <?template name resultSubTemplate>
    <?template name subTemplateName #RELATIVE>
    <?template name ../../foo/bar/templName #RELATIVE>
                                                                  

    <?template if 0 anyFound>
      arbitrary contents if specified boolean field is true, or if
      string-field is non-empty, or if integer or long field is
      non-zero 
    <?template else>
      arbitrary contents otherwise
    <?template /if>
                                                                  

     <?template if -1 fieldName fixedString>
     <?template if 1 fieldName fixedNumber>
     <?template if 2 fieldName 4 otherFieldName>
                                                                  

This permits a specified string, integer or long field to be tested against a fixed string or a fixed number, or against another string, integer or long field, respectively.

In SGML terms, these constructs appear as `processing instructions.' As such, they should pass unmolested and uninterpreted through SGML tools. However, note that these constructs may appear within legitimate tags, as in:

    <orderItem product="<?template slot -1 id #BARE>"
    quantity="<?template slot -1 quantity #BARE>">