Document Archive's Templates

Basics

All pages are created dynamically by a template engine that parses the apropriate template files and fills in all the content. That engine is run at the end of the docarc.pl's runtime. Which template is taken is determined by the layout, the runlevel and the requested format.

Layout

Which layout to use depends on the layout user setting. If the requested template does not exist in that layout, it will be taken from the default layout (standard} entry in layout section of docarc.conf). The user setting may be overridden by setting the layout parameter in the GET or POST request to docarc.pl. The used layout determines the subdirectory in the docarc layouts directory.

Runlevels

All procedures that docarc.pl may do are grouped into runlevels. These include a standard runlevel, search, input, user settings and one for each installed module. When errors occur docarc.pl may switch the runlevel to index at runtime. The specfic runlevel gives the filename to the template.

Formats

Each runlevel may output it's data into different templates according to different formats (default is html). Docarc.pl sets the MIME type according to the requested format which could be html, txt, rdf, xul, or anything else. The format is taken as the filename's extension.

So we have the template's path layout/runlevel.format.

Syntax and Command Set

Template commands are implemented in a XML like style. That means, they are enclosed by < and >, for example >tmpl_var name="userid"/<. By default you have to use the attribute name to pass any arguments. If the argument is only a template variable, you may also write simply the variable name, eg. <tmpl_var userid/>.

All commands are only parsed if the apropriate template section has to be output. That means that a combination of control structures (tmpl_if} and (tmpl_loop) together with template inclusion (tmpl_include) may be used to implement recursions with unlimited recursion depth.

<tmpl_var name="variable_name"/>

This command is substituted with the content of the variable which name is given as the argument. Variable names starting with _ are reserved for internal use. Instead of a variable's name you may also use Perl like expressions (see tmpl_if).

<tmpl_include name="filename"/>

Includes the content of the template named filename. It will be parsed like the original template.

<tmpl_loop name="variable_name"> </tmpl_loop>

The text surrounded by start and end tag will be parsed once for every element of the array variable_name. On every loop contents of variables are reset according to the fields set in the array element: Each field is a map of variable names onto their content that will be used in the loop.

<tmpl_if name="expression"> <tmpl_else/> </tmpl_if>

According to the result of the evalutation of expression the content between start tag and tmpl_else or between tmpl_else and end tag is substituted. If no alternative is used, <tmpl_else/> may be omitted. expression may either be a variable name or a Perl like expression with variable names starting with $ and procedure names starting with &.

Runlevels and variables

Common

The presented variables are available in all runlevels.

Additional to simple Perl functions templates may use &userflags( flags, int ) where flags are the binary coded userflags and int is the number of the flag whose status has to be returned.

index