nokobe/SimpleTemplate
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
Repository files navigation
INTRODUCTION
SimpleTemplate is designed to help separate code from display.
To use SimpleTemplate, one passes predetermined values into a template, which
SimpleTemplate then renders into the final output.
The template uses a special syntax which allows a number of constructs in the
template so that no code needs to (or can) run in the template. Visa versa, no
display information needs to be in the code.
NOTE: by default, SimpleTemplate outputs using the htmlentities() function.
To force htmlentities NOT to be used, add the variable using the [optional]
third argument of zero.
eg.
# will apply htmlentities whenever it appears in the template
$page->add('somevar', $somevar);
# will NOT apply htmlentities whenever it appears in the template
$page->add('somevar', $somevar, 0);
Caveat emptor:
SimpleTemplate is a very simple and limited implementation of StringTemplate.
It is intended only as a stop-gap measure until the real StringTemplate library is
made available. Especially when we lack sufficient administrative privileges on
target systems to install StringTemplate ourselves.
Never-the-less, some effort has been taken to ensure SimpleTemplate is as robust
and useful as possible. Note that SimpleTemplate does not actually parse the
template contents but uses a sequence of str_match and str_replace functions to
simulate the process. As such, certain complexities found in the actual
StringTemplate just aren't practical using this method. Still, for what it does...
its' not bad.
The real StringTemplate (for php) can be found here: http://github.com/ewiger/stringtemplate
SAMPLE USAGE
The Template method is best explained with a simple example:
_____________
__________/ Source code \______________________________
<?PHP
require 'simpleTemplate.php';
$page = new SimpleTemplate('path/to/my/template.html');
$page->add('user', 'David Smith');
$page->add('starsign', 'Leo');
$page->add('male', true);
$page->add('favourites', array('mountain biking', 'reading', 'tennis');
print $page->render();
?>
__________
__________/ Template \______________________________
<html>
<body>
A special welcome to $user$, our newest member.
$user$ is a $starsign$. $if(male)$He$else$She$endif$ lists
$if(male)$his$else$her$endif$ favourite activites as:
<ul>
$favourites:{f|<li>$f</li>}
</ul>
</body>
</html>
_________________
__________/ Rendered output \______________________________
<html>
<body>
A special welcome to David Smith, our newest member.
David Smith is a Leo. He lists
his favourite activites as:
<ul>
<li>mountain biking</li><li>reading</li><li>tennis</li>
</ul>
</body>
</html>
______________________
__________/ Template Constructs: \______________________________
Variable Substitution $var$, $var[value]$
Conditional include $if(condition)$ or $if(!condition)$
....
$endif$
Conditional with else $if(condition)$ or $if(!condition)$
...
$else$
...
$endif$
Where "condition" can be $var$ or $var[value]$
(for legacy reasons, $if(var)$ and $if(!var)$ also work)
If the var is not set, false is assumed
Live template $var:{alias|livetemplate}
(future enhancement)
Live template (complete) $var1,var2:{alias1,alias2|livetemplate}
Template inclusion $template()$
Template inclusion tied to var $var:template()$
Template inclusion mapping a var
to an alias $var:template(alias)$
i1 and i0 1-base and 0-based iteration indexes
_______________________________
__________/ Template Constructs in detail \______________________________
================================================================================
Variable Substitution $var$, $var[value]$
CODE SAMPLE:
$page->add('username', 'Mary');
$page->add('user', array('name' => 'John', 'age' => 35, 'hair' => 'blue'));
TEMPLATE SAMPLE:
The user is $username$
Current user details:
name: $user[name]$
age: $user[age]$
hair colour: $user[hair]$
SPECIAL NOTES:
Do not quote index values in the template
================================================================================
Conditional include $if(condition)$ or $if(!condition)$
....
$endif$
CODE SAMPLE:
$page->add('loggedIn', true);
$page->add('username', 'Jack');
TEMPLATE SAMPLE:
$if(loggedIn)$
Welcome, $username$
$else$
Please enter your username and password
$endif$
SPECIAL NOTES:
If "condition" is an actual BOOLEAN, then it will be evaluated as such.
If the "condition" is not BOOLEAN, then the test effectively becomes a
check of whether the parameter is set at all.
"!" in front of the condition will reverse the evaluated result
You may specify a condition parameter that may not be set at runtime.
This is the only time SimpleTemplate will not generate an error for a
missing parameter. In this situation, any unset parameter will default
to FALSE. This is useful for conditional includes. eg:
$if(results)$
# eg: show results in a table...
$endif$
Another example:
$if(loggedIn)$
greetings $user$
$else$
you are not logged in
$endif$
Parameters used in the body or else clause of a conditional $if()$ will only be
evaluated if the condition matches. Thus, in the above example, the parameter: $user$
will only need to be set if the parameter: $loggedIn$ is set. This lets us do something
like:
$if(errormsg)$
$errormsg$
$endif$
without ever generating an error whenever "errormsg" is not set!
"condition" will only be evaluated as a simple boolean. If you want to use a
more complex condition, you will need to precompute it in the code.
eg. $page->add('condition', <put your complex expression here>);
================================================================================
Live template $var:{alias|livetemplate}$
PURPOSE:
"Live template" is used to repeat a template once for each element of an array.
For example:
$var:{alias|livetemplate}$
is roughly equivalent to:
foreach $var as $alias {
str_replace($alias, $var, $livetemplate)
}
CODE SAMPLE:
$page->add('mylist', array('apple', 'orange', grapefruit'));
TEMPLATE SAMPLE:
<p>My favourite fruits</p>
<ul>
$mylist:{f|<li>$f$</li>}
</ul>
EXPECTED OUTPUT:
<p>My favourite fruits</p>
<ul>
<li>apple</li><li>orange</li><li>grapefruit</li>
</ul>
SPECIAL NOTES:
The alias must be included. The alias can be the same as the variable name.
For instance, in the sample above, you could easily use an alias of
"mylist" instead of "f"
You can include newlines in the live template.
eg:
$mylist:{f|<li>$f$</li>
}
So that the rendered output shows one <li> per line
================================================================================
Template inclusion $template()$
PURPOSE:
Include another template wholly within the current template
CODE SAMPLE:
$page = new SimpleTemplate('templates/main.html')
$page->add('title', 'The Page Title');
TEMPLATES:
header.html:
<html>
<head>
<title>$title$</title>
</head>
<body>
main.html:
$header()$
PAGE CONTENTS GO HERE
$footer()$
footer.html:
</body>
</html>
SPECIAL NOTES:
When referencing templates for inclusion:
1. Do not include the directory or suffix - they are assumed to
be the same as for the original template.
2. All parameters added are also available to all included templates
================================================================================
Template inclusion tied to a variable $var:template()$
PUPOSE:
Similar to Live Template, except that the template code is tucked away
in another file. When no alias is specified (see following section for
"Template inclusion mapping to a variable") then SimpleTemplate assumes a default
of "attr"
This can be used as a simple way to decorate a list. For example, to
revisit the sample from the "Live Template" section...
CODE SAMPLE:
$page->add('mylist', array('apple', 'orange', grapefruit'));
TEMPLATES:
listDecoration.html:
<li><a href="http://dictionary.reference.com/browse/$attr$>$attr$</a></li>
main:
<p>My favourite fruits</p>
<ul>
$mylist:listDecoration()$
</ul>
EXPECTED OUTPUT:
<p>My favourite fruits</p>
<ul>
<li><a href="http://dictionary.reference.com/browse/apple>apple</a></li>
<li><a href="http://dictionary.reference.com/browse/orange>orange</a></li>
<li><a href="http://dictionary.reference.com/browse/grapefruit>grapefruit</a></li>
</ul>
TEMPLATE SAMPLE:
================================================================================
Template inclusion mapping to a variable
to an alias $var:template(alias)$
PURPOSE:
Same as previous section except that you are able to specify your own alias, which
should then be the same variable referenced in the included template