Parser API

Template files

Template files are basic text files. By convention the extension .tpl is used, but this isn't a requirement for the parser. Note that the .tpl extension is mandatory for usage in skins. Right now, the parser is only used for skins to convert from HTML->HTML, but it could also be used for templating in the apache, bind, sendmail, etc. configuration files.

In order to use the features of the parser, you haev to include tags into the template. Tags consist of text surrounded two accolades (Example: {tag}). Right now there are 7 (or 8) different types of tags: 3 basic and 4 special tags. The parser will continue until there are no more replacable tags present. This means that if something gets replace by text which itself contains a valid tag, that new tag will also get replace. This makes it possible to create infinite loops, so care should be taken, although it doesn't generally pose a problem.

Basic tags

Variables

Template

Text {var} Text

PHP

$parser->AddVar('var', 'replacement');

Result

Text replacement Text

Description

These are the most basic type of tags, any occurence of {var} will be replace by the replacement specified in the AddVar? call.

Language Variables

Template

Text {L:example} Text

PHP

$T['example'] = 'Translated Example';

Result

Text Translated Example Text

Description

Variables beginning with L: are special. These are automatically replaced by the appropriate entry in the language files.
More complex example: {L:panel:1} will be replaced by $T['panel'][1]

Conditionals

Template

Line 1: Text {ok}Single{/ok} Text
Line 2: Text {ok}Yes{/ok/}No{/ok} Text

PHP

$parser->AddIf('ok', false);

Result

Line 1: Text Text
Line 2: Text No Text

Description

Conditionals have two forms.

• The first has a simple opening and closing tag. If the conditional was set to true, everything inside will be in the output. If set to false the content will be removed.
• The second form has an additional "else". If set to true, the first part will be in the output, otherwise the second part will be.

Iteration

Template

<ul>
{list}

<li>{item}</li>

{/list}
</ul>

PHP

$parser->AddClass('list'); $parser->AddVar('item', 'first', 'list"); $parser->NextClass('list'); $parser->AddVar('item', 'second', 'list");

Result

<ul>

<li>first</li>
<li>second</li>

</ul>

Description

Iteration is the most complex basic tag. All tag related methods have an optional last parameter which defined in which "class" they belong. In the example a variable is added to the class "list". Classes can also be nested inside other classes.

After you have added a set of variables, etc. to a class, you call NextClass the advance to a new set.

There is also a method called StripClass whose purpose is to undo the last NextClass. This is useful if you use add classes using foreach loops. If called on an empty class, the class will behave as if it was a conditional set to false.

Special tags

Special tags are used by template designers only and can only very limitedly be manipulated using code.

Comments

Example

Text {* this is a comment *} Text

Result

Text Text

Description

Everything between {* and *} will not be output. It can be used to add comments to a file, or comment out unwanted parts of a template.

Includes

Example

Text {#other.tpl} Text

Description

{#file.tpl} will be replaced with the contents of file.tpl. That file will also be processed by the parser.

Wrapping

Example

Before {!main.tpl}Inside{/!main.tpl} After

Example (main.tpl)

MainBefore {main page} MainAfter

Result

Before MainBefore Inside MainAfter After

Descrpition

Everything between the opening and closing tags will be replaced by the contents of the specified file. In addition, {main page} in that file will be replaced by whatever was inside the tags.

If you ommit the closing tag, it is assumed that the closing tag is at the end of the file.

Setting variables

Example

{$var}Value{/$var} Var: {var}

Result

Var: Value

Description

This may seem pretty useless, but allows you to specify variables for other files. This becomes useful in combination with {!main.tpl} if for example main.tpl contains a {title} tag.

Setting variables is used by web-cp for frames. Each frame sets a TARGET variable and in the URLs generated in code all instances of {TARGET} will be replaced by the correct target frame.