First off I'll go ahead and start out with Smarty, since I've used it quite a lot. Since this is a community wiki, feel free to plug in examples of your own templating engine should you choose.
Installing Smarty
Templating provides a great way of structuring your HTML and separating out your HTML content from your logic code. It also provides a way to organize individual components of your HTML page, so it's easier to manage, and is more re-usable.
To start, we'll take at showing a simple page with Smarty. First off you need to actually get Smarty. So we'll head down to the Smarty download page. As of this writing, the latest stable version is Smarty 3.0.7, so we'll go ahead and download that. Downloading the .tar.gz file or the .zip file is up to the system you have. For Windows and Mac users (most likely using MAMP or XAMPP), .zip is probably a good choice, though you can always get programs to handle .tar.gz files. Users with Linux or *BSD type systems can grab the .tar.gz version.
Now then, we extract the file and get the following directory layout:
COPYING.lib
demo/
libs/
|__ Smarty.class.php
|__ ... some other files and folders ...
README
SMARTY2_BC_NOTES
Now, Smarty.class.php is the main file we're going to include to use Smarty. It's located in the libs directory. As 'libs' is a pretty generic sounding name, we're going to copy this to our document root folder, and rename it to Smarty. Now our theoretical document root folder is currently empty, so it will end up looking like this:
Smarty/
|__ Smarty.class.php
|__ ... some other files and folders ...
A Simple Template
Now that Smarty is installed, we'll create a very basic template and php script to show how it works. First off, to keep things organized we'll make a templates folder to keep our templates in. Then we'll create a mypage.php file, and a mypage.tpl file in our templates folder:
mypage.php
templates/
|__ mypage.tpl
Smarty/
|__ Smarty.class.php
|__ ... some other files and folders ...
mypage.php
<?php
require_once('Smarty/Smarty.class.php');
$smarty = new Smarty();
$smarty->assign("MYVAR", "Hello World");
$smarty->display("templates/mypage.tpl");
?>
templates/mypage.tpl
<html>
<head>
<title>My Sample Page</title>
</head>
<body>
<h1>{$MYVAR}</h1>
</body>
</html>
Now if we navigate to mypage.php, for example http://localhost:8000/mypage.php, "Hello World" will be displayed in large bold text. So what happend? Let's step through the code:
require_once('Smarty/Smarty.class.php');
Here we include the main Smarty class. We need this for any and all Smarty functionality.
$smarty->assign("MYVAR", "Hello World");
You'll be using this a lot. The assign command takes a value, "Hello World" in this example, and assigns it to a name, "MYVAR". If you look at the template:
<h1>{$MYVAR}</h1>
You'll notice {$MYVAR}. The {}'s indicate to Smarty that it needs to evaluate the expression inside. This could be a command or simply a variable. It could produce output or simply set a variable value. In this case, it simply outputs the value of $MYVAR that we assigned.
$smarty->display("templates/mypage.tpl");
Finally, we tell Smarty to parse the template, then display it as if you had simply echo'ed out HTML in a PHP page. Fancy eh? Now, a lot of people will want to iterate through arrays (ie. a set of db results), so let's take a look at an example of how to achieve that.
Looping Through Arrays
First we'll make adjustments to our code. The new listings are as follows:
mypage.php
<?php
require_once('Smarty/Smarty.class.php');
$myarray = array(
"John",
"Jane",
"Henry",
"Nancy",
"Gorilla"
);
$smarty = new Smarty();
$smarty->assign("MYARRAY", $myarray);
$smarty->display("templates/mypage.tpl");
?>
templates/mypage.tpl
<html>
<head>
<title>My Sample Page</title>
</head>
<body>
<h1>Results</h1>
<ul>
{foreach $MYARRAY as $myvalue}
<li>{$myvalue}</li>
{/foreach}
</ul>
</body>
</html>
If you reload the page, you'll get something like this:
Now, there are only a few changes to note:
$smarty->assign("MYARRAY", $myarray);
Instead of a string value, we assigned a variable which holds an array. This was passed to Smarty which used the data in the {foreach} loop:
<ul>
{foreach $MYARRAY as $myvalue}
<li>{$myvalue}</li>
{/foreach}
</ul>
The foreach in Smarty is much like the foreach of PHP. In this case, Smarty takes the array that was assigned to $MYVALUE and loops through it, setting $myvalue to the result of the current loop value. From there we can use {$myvalue} to refer to each individual item. Now, let's say we want to make this unordered list a widget to reuse in other places. We can do that through using templates themselves as variables.
Template Modularization
HTML can get very long very quickly. Smarty helps manage this by letting you break out parts of the page into individual components. So what we'll do is take our unordered list and put it into a separate page. Our new code will look like this:
mypage.php
<?php
require_once('Smarty/Smarty.class.php');
$myarray = array(
"John",
"Jane",
"Henry",
"Nancy",
"Gorilla"
);
$smarty = new Smarty();
$smarty->assign("MYARRAY", $myarray);
$content = $smarty->fetch("templates/mycontent.tpl");
$smarty->assign("MYCONTENT", $content);
$smarty->display("templates/mypage.tpl");
?>
templates/mypage.tpl
<html>
<head>
<title>My Sample Page</title>
</head>
<body>
<h1>Results</h1>
{$MYCONTENT}
</body>
</html>
mycontent.tpl
<ul>
{foreach $MYARRAY as $myvalue}
<li>{$myvalue}</li>
{/foreach}
</ul>
The result we get is the same, however the backend is now more organized. We can now reuse this mycontent.tpl file in other pages if we want. Common usages of this organization is making header, footer, and other parts of the page individual templates. This lets you narrow down to relevant pieces.
So what happened on the backend? The important command to take note of here is:
$content = $smarty->fetch("templates/mycontent.tpl");
fetch() works like display, except that instead of outputting it right away, it returns the result as a string of the rendered HTML. Note that because $MYARRAY is used in the mycontent.tpl, we have to assign the array right before it, not right before the final display() call. This ordering is important!
Conclusion
This concludes the very basic introduction to Smarty, and using a templating engine to work with managing your content. The Smarty Documentation provides a great resource for seeing all that smarty is capable of. Be sure to look through all the available commands to make sure you're using it efficiently!
