Introduction - template syntax -- Creating and editing templates
Placeholders
The default format of placeholder is
This means, the name of the placeholder can consist of upper- and lowercase
letters, underscores and hyphens. The name must be placed between curly
brackets without any spaces.
Actual values for the placeholders are set using setVariable() and setGlobalVariable() methods. Placeholders for which no values were set are removed from output by default.
Blocks
The format of a block is
<!-- BEGIN [0-9A-Za-z_-]+ -->
... block content ...
<!-- END [0-9A-Za-z_-]+ --> |
The rules for the block name are the same like for placeholders.
In contrast to placeholders the spaces in the block markup are
required.
The nesting of blocks is permitted, but be careful while
parsing. You have to parse() the innermost block first and then go from inner to outer.
In Sigma the whole template itself is treated as a virtual block called
"__global__". Most block-related functions use this block
name as default.
<!-- INCLUDE --> statements
It is possible to include a template file from within another template file using an <!-- INCLUDE filename --> statement:
... some content ...
<!-- INCLUDE filename.html -->
... some more content ... |
When such a template file gets loaded, the
<!-- INCLUDE filename.html --> will be replaced by contents of
filename.html.
Some things to note:
Although this functionality is implemented using addBlockfile(), unlike addBlockfile() no new blocks are created in the template.
<!-- INCLUDE --> calls are processed before any variable substitution can take place. So <!-- INCLUDE {placeholder} --> will not work unless you actually have a file named {placeholder} and want to load it.
Template functions
Sigma templates can contain simple function calls. This means that the author of the template can add a special placeholder to it
... some content ...
func_h1("embedded in h1")
... some more content ... |
Sigma will parse the template for these placeholders and will allow you to define a callback function for them via
setCallbackFunction(). Callback will be called automatically when the block containing such function call is
parse()'d.
Format of such function name is as follows
func_[_a-zA-Z]+[A-Za-z_0-9]* |
that means that it should start with a 'func_' prefix, then has a letter or an undercore and then a sequence of letters, digits or underscores. Arguments to these template functions can contain variable placeholders
func_translate('Hello, {username}') |
but not blocks or other function calls.
Shorthand for template functions
Since release 1.1.0, instead of using
you can write
There are 3 automatically registered template functions
Thus, if you add {var:h} placeholder to the template, var will be have unsafe characters replaced by corresponding HTML entitites.
Usage Example
Other usage examples: There are several usage examples in the package archive that cover most of its functionality. You are encouraged to review them along with the docs.
Example 31-1. The table.html template file <html>
<body>
<table cellpadding="2" cellspacing="0" border="1">
<!-- INCLUDE table_header.html -->
<!-- BEGIN table_row -->
<tr>
<td bgcolor="func_bgcolor('#CCCCCC', '#F0F0F0')">{first_name}</td>
<td bgcolor="func_bgcolor('#CCCCCC', '#F0F0F0')">{last_name}</td>
</tr>
<!-- END table_row -->
</table>
</body>
</html> |
|
Example 31-3. The script <?php
require_once 'HTML/Template/Sigma.php';
function toggle($item1, $item2)
{
static $i = 1;
return $i++ % 2? $item1: $item2;
}
$data = array (
array("Stig", "Bakken"),
array("Martin", "Jansen"),
array("Alexander", "Merz")
);
$tpl =& new HTML_Template_Sigma('.');
$tpl->loadTemplateFile('table.html');
$tpl->setCallbackFunction('bgcolor', 'toggle');
foreach ($data as $name) {
// assign data
$tpl->setVariable(array(
'first_name' => $name[0],
'last_name' => $name[1]
));
// process the block
$tpl->parse('table_row');
}
// print out the output
$tpl->show();
?> |
|
Example 31-4. The output <html>
<body>
<table cellpadding="2" cellspacing="0" border="1">
<tr>
<th>First name</th>
<th>Last name</th>
</tr>
<tr>
<td bgcolor="#CCCCCC">Stig</td>
<td bgcolor="#CCCCCC">Bakken</td>
</tr>
<tr>
<td bgcolor="#F0F0F0">Martin</td>
<td bgcolor="#F0F0F0">Jansen</td>
</tr>
<tr>
<td bgcolor="#CCCCCC">Alexander</td>
<td bgcolor="#CCCCCC">Merz</td>
</tr>
</table>
</body>
</html> |
|