Introduction - template syntax
Placeholders
The default format of placeholder is
{[0-9A-Za-z_-]+}
This means, the name of the placeholder can consist of upper- and lowercase letters, numbers, 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:
-
<!-- INCLUDE -->statements are only processed when loading the template files from disk. If you use setTemplate() method to set the template or addBlock() and replaceBlock() to work with its blocks, then<!-- INCLUDE -->statements in these templates will not be replaced! -
Although this functionality is implemented using addBlockfile(), unlike addBlockfile() no new blocks are created in the template.
-
<!-- INCLUDE -->statements 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.
Quoting of template function arguments
The information in this section applies to HTML_Template_Sigma version 1.1.2 and later, please upgrade if you have problems with template function arguments in previous versions.
Quoting of function arguments is not mandatory, the following is a perfectly valid template function:
func_uppercase(Some unquoted text)
But consider the following: function arguments are contained within
parentheses and separated by commas. Therefore if closing parenthesis
')' or comma ','
appears in function argument, it should be quoted.
The next thing to consider is that HTML_Template_Sigma is mostly targeted for generating HTML. Therefore a quoted string within an argument is most probably a tag attribute. The contents of such strings are not parsed for commas and parentheses. Therefore the following is also a perfectly valid template function:
func_foo(<a href="javascript:foo(bar, baz)">Do foo</a>)
But if you have an unmatched single or double quote in your argument or if the argument starts with a quote, it should be quoted.
Finally, the argument should be quoted if it is an empty string or if its leading or trailing whitespace is significant (leading and trailing whitespace will be removed from unquoted arguments).
The arguments can be quoted using either single or double quotes. If an
argument contains a quote of the same type, then it should be escaped using
the backslash symbol '\'. The backslash symbol
itself should also be escaped,
func_foo('O\'really')
func_foo('AC\\DC')
will pass O'really and AC\DC to
the relevant callbacks.
Valid and invalid template function arguments
Valid arguments:
func_foo(Some unquoted text)
func_foo("Some quoted text")
func_foo(<a href="javascript:foo(bar, baz)">Do foo</a>)
func_foo('O\'really')
func_foo('AC\\DC')
Invalid arguments:
func_foo(Hello, {username}) contains a comma, will yield two arguments instead of one
func_foo(O'really) unmatched single quote
func_foo('O'really') unescaped single quote
func_foo(, 'whatever') empty arguments should be quoted
Shorthand for template functions
Since release 1.1.0, instead of using
func_callback({var})
you can write
{var:callback}
There are 3 automatically registered template functions
- 'h' for htmlspecialchars()
- 'e' for htmlentities() (available since release 1.2.0)
- 'u' for urlencode()
- 'r' for rawurlencode() (available since release 1.2.0)
- 'j' for a method of Sigma that escapes the string for usage in Javascript string constants.
Thus, if you add {var:h} placeholder to the template, var will be have unsafe characters replaced by corresponding HTML entitites.
Since release 1.2.0 it is possible to provide the charset parameter for 'h' and 'e' callbacks via setOption().
Template comments
Since release 1.2.0 it is possible to add comments to the template file:
<!-- COMMENT -->
Some text here
<!-- /COMMENT -->
These comments will be removed from the output, unlike standard HTML comments.
Customizing the template syntax
It is possible to somewhat customize the syntax of templates by changing regular expressions (or their parts) used by Sigma for parsing.
The actual regular expressions used to parse templates are generated in constructor using parts specified as class properties. It is generally not safe to change the generated regular expressions (as their format is hardcoded in several places throughout Sigma), but you can override the properties:
- $openingDelimiter
- Start of variable placeholder, defaults to
'{'
- $closingDelimiter
- Start of variable placeholder, defaults to
'}'
- $blocknameRegExp
- Regular expression part for block names, defaults to
'[0-9A-Za-z_-]+'
- $variablenameRegExp
- Regular expression part for placeholder names, defaults to
'[0-9A-Za-z._-]+'
- $functionnameRegExp
- Regular expression part for function names, defaults to
'[_a-zA-Z][A-Za-z_0-9]*'
- $includeRegExp
- Complete regular expression for processing file inclusion, defaults to
'#<!--\s+INCLUDE\s+(\S+)\s+-->#im'
- $commentRegExp
- Complete regular expression for removing template comments, defaults to
'#<!--\s+COMMENT\s+-->.*?<!--\s+/COMMENT\s+-->#sm'
To customize some of the above parts you need to subclass
HTML_Template_Sigma and override the relevant properties
so that generated regular expressions will use the new parts. For example,
if you want to prevent Sigma treating {1} (which may appear
as a part of Javascript regular expression) as a placeholder (see
bug #18147)
you can do the following
<?php
class SanerPlaceholders extends HTML_Template_Sigma
{
var $variablenameRegExp = '[A-Za-z_][0-9A-Za-z._-]*';
}
$tpl = new SanerPlaceholders();
$tpl->setTemplate('{foo} {1} {bar}');
$tpl->setVariable('foo', 'foo value');
$tpl->show();
?>
Usage Example
Other usage examplesThere are several usage examples in the package archive that cover most of its functionality. You are encouraged to review them along with the docs.
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>
The table_header.html template file
<!-- COMMENT -->
This text will not appear in output.
<!-- /COMMENT -->
<tr>
<th>First name</th>
<th>Last name</th>
</tr>
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();
?>
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>