CoTemplate Statements

This document covers features, statements and their syntax supported by CoTemplate v.2.7 and later.

#1. Blocks

Blocks are the largest elements in the template's structure. Templates consist of blocks, blocks consist of other blocks, statements, tags and raw text. Here is the block syntax:

<!-- BEGIN: BLOCK_NAME -->
Block HTML contents here
<!-- END: BLOCK_NAME -->

Most templates have one root-level block named MAIN, but multiple root-level blocks in one template file are allowed. HTML outside the root-level blocks is ignored.

Block names are given in upper case. This is a common rule.

Blocks are triggered and pushed to output by controller PHP code. Blocks can be referenced by their full name, e.g. 'PARENT_BLOCK.BLOCK_NAME'. And blocks are slightly faster than other statements. These 3 facts make them fundamental building blocks in CoTemplate.

#2. Tags

Variables in CoTemplate are called TPL Tags or just Tags. There are 2 kinds of tags depending on their scope: local tags and global tags.

Local tags are assigned with XTemplate::assign() method in controller PHP code. Their syntax is:

{TAG_NAME}

Such a statement will be substituted with current value of a locally assigned variable in the XTemplate object with name 'TAG_NAME'. Local tag names are given in upper case, this common rule allows us to distinct TPL tags quite easily from the other code.

Global tags are just global PHP variables, they have PHP keyword in their name:

{PHP.my_var}

Although it is recommended to use local tags for most of the output, global tags are used to output global variables which are available in many blocks and templates or to compensate the lack of a specific local tag.

#2.1. Arrays and objects

Tags can be used to access arrays and objects with public properties. Dot notation is used to specify array keys or property names:

{ARRAY_TAG_NAME.array_key_name}
{OBJECT_TAG_NAME.object_property_name}
{PHP.global_var_name.key_name}

Arrays/objects can be nested. The same notation is used to access nested elements:

{TAG_NAME.level1_key.level2_key}

There is no limit on nesting level, but the deeper the level, the slower such a tag works.

#2.2. Callbacks

Callbacks provide the way to process data with some functions before output. Pipe character is used to separate callback from the tag being processed:

{TAG_NAME|function_name}

This will be substituted with the result of function 'function_name' called on the value of tag 'TAG_NAME', where 'function_name' is the name of any valid PHP function that takes 1 string argument and returns a string value, including built-in PHP functions and user functions.

If there are more than 1 argument, braces can be used to specify them. The syntax is similar to PHP function call.Arguments can be scalar values (integer, float, string, bollean or null), other tags (including tags containing other functions calls) and the keyword $this, which is replaced with the current value of the tag or a previous callback result:

{MY_TAG|substr($this, 3, 'foo')}
{MY_TAG|someFunc(30.5, $this 'bar', {ANOTHER_TAG}, {PHP.someVar}, null, true)}

Multiple callbacks are supported, the result of the previous callback is "piped" to the next callback. Example:

{MY_STRING|str_replace('foo', 'bar', $this)|htmlspecialchars}

Callbacks and array/object access can be mixed together:

{MY_TAG.item1|doSomething|mb_strtoupper}

Global tags are processed with callbacks too. There is a special use of global tags + callbacks which allows you to invoke PHP functions without processing any actual tags:

{PHP|myFunctionCall('some data', 10, {SOME_TAG}, false)}

It is not recommended to turn your TPL files into PHP spaghetti, so use them carefully.

#3. FILE statements

FILE statements are used to include TPL files within other TPL files. The syntax is:

{FILE "path/to/file.tpl"}

The path is relative to the root of your website. You can use TPL tags within the path, e.g.:

{FILE "{PHP.cfg.plugins_dir}/{PHP.theme}/something.tpl"}

Inclusion is performed quite literally: the contents of the given file are inserted exactly in the place of the FILE statement before any further parsing/processing of the current template.

#4. IF statements

IF statements are used to render parts of the template depending on logical conditions at run-time. IF statements are also known as conditional or logical blocks. A simple IF statement syntax:

<!-- IF expression -->
  some HTML/TPL code here
<!-- ENDIF -->

The contents of the logical block is rendered if the expression evaluates to TRUE. The syntax of expressions is similar to PHP comparison and boolean expressions and may consist of TPL tags, literals, operators and parenthesis. The list of all supported operators is avialable here.

IF/ELSE syntax is also supported:

<!-- IF {FOO} > 10 AND ({PHP.bar} OR {BAZ} ~= 'boo') -->
  This is rendered if the condition is TRUE.
<!-- ELSE -->
  This is rendered if the condition is FALSE.
<!-- ENDIF -->

Conditional blocks may contain other blocks, other IF and FOR statements, tags, FILE statements and raw HTML.

#5. FOR statements

FOR statements are used to iterate over the data which doesn't have any special iteration blocks provided. The most generic syntax is:

<!-- FOR {VALUE} IN {MY_ARRAY} -->
Some use of {VALUE}
<!-- ENDFOR -->

or

<!-- FOR {KEY}, {VALUE} IN {MY_ARRAY} -->
Some use of {KEY} and {VALUE}
<!-- ENDFOR -->

Where 'MY_ARRAY' is the name of the tag which contains the actual data which is being looped over. 'KEY' and 'VALUE' are the names of the tags which are used to access array elements inside the loop; {VALUE} represents the value of the current item, {KEY} represents a string or an integer key of the item within the array.

Callbacks can be used to provide almost limitless looping and processing possibilities. Below some common examples are represented.

<ul>
<!-- FOR {KEY}, {VALUE} IN {MY_ARRAY}  -->
  <li><strong>{VALUE.title}: </strong> <input name="{KEY}" type="text" value="{VALUE.text|htmlspecialchars}" /></li>
<!-- ENDFOR -->
</ul>

Traditional loop within an integer range:

<!-- FOR {INDEX} IN {PHP|range(1,10)} -->
  {INDEX}<!-- IF {INDEX} < 10 -->,<!-- ENDIF -->
<!-- ENDFOR -->

Loop from 10 downto 2 with a negative step of -2:

<!-- FOR {NUM} IN {PHP|range(10, 2, -2)} -->
  {NUM}<br />
<!-- ENDFOR -->

FOR loops may conatin other nested FOR loops, IF statements, FILE includes, blocks, tags and raw HTML data.

Key and value tags are assigned in the common tag scope. There is no stack/scoping in CoTemplate.