Crash Course
For those of you who have used PHP template engines, the basic concepts of
Smarty should look quite familiar. In your PHP application you assign variables
for use in the template, then you display it.
| index.php |
include('Smarty.class.php');
// create object
$smarty = new Smarty;
// assign some content. This would typically come from
// a database or other source, but we'll use static
// values for the purpose of this example.
$smarty->assign('name', 'george smith');
$smarty->assign('address', '45th & Harris');
// display it
$smarty->display('index.tpl');
|
The template file then contains the output interspersed with tags that Smarty
replaces with assigned content.
| index.tpl | | output |
<html>
<head>
<title>User Info</title>
</head>
<body>
User Information:<p>
Name: {$name}<br>
Address: {$address}<br>
</body>
</html>
|
|
<html>
<head>
<title>User Info</title>
</head>
<body>
User Information:<p>
Name: george smith<br>
Address: 45th & Harris<br>
</body>
</html>
|
As you can see, Smarty cleanly separates your presentation elements (HTML, CSS,
etc.) from your application code. However, it does not necessarily separate
logic entirely from your templates. With respect to Smarty's design
principles, so long as the logic in the templates is for presentation
only, it is permissible to use it. For instance, looping over table row
colors or including one template from another would be considered presentation
logic. This is something the application should not need to accomodate (it just
supplies an array of data.) The idea is to keep the template designer role and
application programming role separated. You should be able to completely tear
down the templates and rebuild them without touching the code base, all while
retaining full control of the presentation. With this comes an important point:
there is nothing stopping you from putting application logic in the template.
Smarty has more than enough power to let you shoot yourself in the foot, so you
must have some self discipline in this respect. Don't worry though, with a little
bit of practice it becomes quite self-evident what logic belongs where.
Smarty has some nice features that take advantage of this design principle, as
you'll see in the next example. One prominant feature of Smarty is variable
modifiers. These are used to alter the output of assigned variables
from within the template. In our example, we would like to display George's
name capitalized, and we would like to properly HTML escape the amphersand
(&) symbol in the address. We also show how to display the current date
with a custom formatting.
| index.tpl | | output |
<html>
<head>
<title>User Info</title>
</head>
<body>
User Information:<p>
Name: {$name|capitalize}<br>
Addr: {$address|escape}<br>
Date: {$smarty.now|date_format:"%Y-%m-%d"}<br>
</body>
</html>
|
|
<html>
<head>
<title>User Info</title>
</head>
<body>
User Information:<p>
Name: George Smith<br>
Addr: 45th & Harris<br>
Date: 2003-12-19<br>
</body>
</html>
|
Using modifiers, we have just handed formatting control of the assigned content
over to the template and out of the application logic. Now we can assign the
raw data straight to the template (no mods necessary for presentation
purposes!) You can chain any number of modifiers together on one variable,
making this feature quite flexible. There are many more modifiers that come with Smarty,
or you can make your own with its easy to use plugin architecture. Drop your new modifier
into the plugin directory, then mention it in the template!
Smarty also has what are known as template functions. Template
functions carry out tasks in the template that may or may not display content.
For example, you can include other templates from within a template with the
include function. Let's say you have many templates with the same header
and footer information. You can manage these as separate templates and include
them.
| header.tpl | | footer.tpl |
<html>
<head>
<title>{$title|default:"no title"}</title>
</head>
<body>
|
|
</body>
</html>
|
| index.tpl | | output |
{include file="header.tpl" title="User Info"}
User Information:<p>
Name: {$name|capitalize}<br>
Address: {$address|escape}<br>
{include file="footer.tpl"}
|
|
<html>
<head>
<title>User Info</title>
</head>
<body>
User Information:<p>
Name: George Smith<br>
Address: 45th & Harris<br>
</body>
</html>
|
One feature of the include function is locally scoped variables. Notice that
$title is a template variable not assigned directly to the template, but
assigned by passing it as an attribute to the include function. This way
the $title variable is only available within the scope of the header
template, and can be dynamically changed any time the header.tpl file is
included. Also, notice we used the default modifier on $title so
in the case $title is empty, the text "no title" will show up
instead of displaying nothing.
There are some nice functions that automate tasks such as html dropdown boxes.
One is html_options. You assign the arrays of data to the template, then
this function does all the work to generate the HTML output for it.
| index.php |
include('Smarty.class.php');
// create object
$smarty = new Smarty;
// assign options arrays
$smarty->assign('id', array(1,2,3,4,5));
$smarty->assign('names', array('bob','jim','joe','jerry','fred'));
// display it
$smarty->display('index.tpl');
|
| index.tpl |
<select name=user>
{html_options values=$id output=$names selected="5"}
</select>
|
| output |
<select name=user>
<option label="bob" value="1">bob</option>
<option label="jim" value="2">jim</option>
<option label="joe" value="3">joe</option>
<option label="jerry" value="4">jerry</option>
<option label="fred" value="5" selected="selected">fred</option>
</select>
|
Smarty facilitates a convenient way to loop over arrays of data with the
section function. Here's an example of that, and we also threw in
alternating row colors via the cycle function, and we use the
strip function to strip out newlines and white space.
| index.php |
include('Smarty.class.php');
// create object
$smarty = new Smarty;
// assign an array of data
$smarty->assign('name', array('bob','jim','joe','jerry','fred'));
// assign an associative array of data
$smarty->assign('users', array(
array('name' => 'bob', 'phone' => '555-3425'),
array('name' => 'jim', 'phone' => '555-4364'),
array('name' => 'joe', 'phone' => '555-3422'),
array('name' => 'jerry', 'phone' => '555-4973'),
array('name' => 'fred', 'phone' => '555-3235')
));
// display it
$smarty->display('index.tpl');
|
| index.tpl |
<table>
{section name=mysec loop=$name}
{strip}
<tr bgcolor="{cycle values="#eeeeee,#dddddd"}">
<td>{$name[mysec]}</td>
</tr>
{/strip}
{/section}
</table>
<table>
{section name=mysec loop=$users}
{strip}
<tr bgcolor="{cycle values="#aaaaaa,#bbbbbb"}">
<td>{$users[mysec].name}</td>
<td>{$users[mysec].phone}</td>
</tr>
{/strip}
{/section}
</table>
|
| output |
<table>
<tr bgcolor="#eeeeee"><td>bob</td></tr>
<tr bgcolor="#dddddd"><td>jim</td></tr>
<tr bgcolor="#eeeeee"><td>joe</td></tr>
<tr bgcolor="#dddddd"><td>jerry</td></tr>
<tr bgcolor="#eeeeee"><td>fred</td></tr>
</table>
<table>
<tr bgcolor="#aaaaaa"><td>bob</td><td>555-3425</td></tr>
<tr bgcolor="#bbbbbb"><td>jim</td><td>555-4364</td></tr>
<tr bgcolor="#aaaaaa"><td>joe</td><td>555-3422</td></tr>
<tr bgcolor="#bbbbbb"><td>jerry</td><td>555-4973</td></tr>
<tr bgcolor="#aaaaaa"><td>fred</td><td>555-3235</td></tr>
</table>
|
Smarty also has built-in caching capabilities to help speed up the page
rendering. A copy of the template output is stored in a text file, then that is
displayed upon subsequent calls to the request instead of dynamically rendering
the page each time. This can speedup page rendering substantially, especially
if there is a lot of processing involved to create the page such as database
calls and variable assignments.
| index.php |
include('Smarty.class.php');
// create object
$smarty = new Smarty;
$smarty->caching = true;
// see if the page is already cached
if(!$smarty->is_cached('index.tpl')) {
// not cached, so you might do some database queries here,
// then assign the returned content. We just use static
// values for this example.
$smarty->assign('name', 'george smith');
$smarty->assign('address', '45th & Harris');
}
// display it
$smarty->display('index.tpl');
|
You can also have multiple cached versions of a single page by passing
a unique cache id to the display() function, check out the docs on that one!
There are many more builtin and custom functions that come
with Smarty, or you can make your own, again with the easy to use plugin architecture.
Again, we'll take note that all of the functionality of Smarty (modifiers,
functions, etc.) deal exclusively with the presentation of content. This
is the design principle Smarty was built upon.
|
