SMARTY QUICKSTART GUIDE
-----------------------
So you don't like reading documentation either? This guide is to help you
immediately get your feet wet in Smarty, get a feel for how it works and if it
will work for you.
We make a few assumptions here, such as you already have PHP installed on your
web server, you know the basics of unix file permissions, the basics of PHP and
how it works, etc. If you are using Smarty in a non-unix environment, you
should understand the difference in your OS regarding file permissions.
INSTALLATION
------------
Unpack the Smarty tarball. You will see four class files: Smarty.class.php,
Smarty.addons.php, Smarty_Compiler.class.php and Config_File.class.php. You
will need to have all three of these files somewhere in your PHP include path,
so when you call require("Smarty.class.php") from within your application, it
can find the class.
Smarty uses the PEAR libraries for some of its error handling routines. PEAR
libraries come with the distribution of PHP. Be sure that the path to these
libraries is included in your php include_path. Unix users check
/usr/local/lib/php. Windows users check C:/php/pear.
Now change directories somewhere inside of your web server document root. For
this guide, we'll create a directory under the document root named "Smarty",
and put all of our work here.
$> cd /home/htdocs
$> mkdir Smarty
$> cd Smarty
now, we need to create a few directories for Smarty to use:
$> mkdir templates
$> mkdir templates_c
$> mkdir configs
Smarty needs to be able to write to the templates_c directory. It is
recommended that you change the ownership and write permissions such that the
web server user (usually nobody) has write access to this directory. You can
chmod 777 the directory, but be aware of security concerns on multi-user
systems. See the documentation for more info on this.
$> chown nobody:nobody templates_c
$> chmod 700 templates_c
$> ls -l
drwxrwxr-x 2 user group 512 Jan 18 14:18 configs/
drwxrwxr-x 2 user group 512 Jan 18 14:18 templates/
drwx------ 2 nobody nobody 512 Jan 18 14:18 templates_c/
Or alternately (less secure):
$> chmod 777 templates_c
$> ls -l
drwxrwxr-x 2 user group 512 Jan 18 14:18 configs/
drwxrwxr-x 2 user group 512 Jan 18 14:18 templates/
drwxrwxrwx 2 user group 512 Jan 18 14:18 templates_c/
Now we need to create two files, index.php and templates/index.tpl. index.php
is the file that we will be calling from our web browser. index.tpl is the file
that Smarty will use as it's template file. (.tpl files are never called
directly from the browser, only Smarty calls them.)
--------- index.php --------
assign("Name","Ned");
$smarty->display("index.tpl");
?>
--------- templates/index.tpl --------
Hello
Hello, {$Name}!
Now, view the index.php file from your web browser:
http://your.host.com/Smarty/index.php
You should see "Hello, Ned!" in your browser. If not, retrace the steps above
and make sure you follow the instructions exactly as they say. Also check the
installation instructions in the documenation, and check your installation of
PHP to be sure things are setup properly.
You see "Hello, Ned!" in your browser? Good!
What happened here is Smarty took the index.tpl file and compiled it into a php
script which you can take a look at in the templates_c directory. Smarty will
continue to use this compiled script until the index.tpl file is changed, then
it will automatically recompile. What this means for you: forget about the
templates_c directory. Out of sight, out of mind. You don't need to worry about
it, Smarty takes care of this technical stuff. Out of curiosity, you can see
how your templates look as compiled php scripts, but please don't edit them!
Now that we have Smarty functioning properly, let's get into the guts of Smarty
and learn what thing is all about. I'll try to briefly show examples to cover
the most important features of Smarty.
ASSIGNING VARIABLES
-------------------
Assigning variables to the template is very similar to the ways other template
engines do it. Example:
--------- index.php --------
assign("Name","Ned");
$smarty->assign(array(
"FirstName" => "Ned",
"LastName" => "Flanders",
"Address" => "Springfield"
));
$zipcode = "55555";
$smarty->assign("Zipcode",$zipcode);
$smarty->display("index.tpl");
?>
--------- templates/index.tpl --------
Hello
Hello, {$Name}!
{$FirstName}, {$LastName}
{$Address}, {$Zipcode}
You can assign variables either one by one, or as an associative array. There
is also a way to append to assigned variables. See the documentation for
details.
INCLUDE
-------
Now, let's see how Smarty can be used to include other template files. This is
handy if you have repetitive template data, such as headers and footers. You
will need to create a couple more template files: templates/header.tpl and
templates/footer.tpl.
--------- index.php --------
assign("Name","Ned");
$smarty->assign(array(
"FirstName" => "Ned",
"LastName" => "Flanders",
"Address" => "Springfield"
));
$zipcode = "55555";
$smarty->assign("Zipcode",$zipcode);
$smarty->display("index.tpl");
?>
--------- templates/index.tpl --------
{include file="header.tpl" title="Home Page"}
Hello, {$Name}!
{$FirstName}, {$LastName}
{$Address}, {$Zipcode}
{include file="footer.tpl"}
--------- templates/header.tpl --------
{$title|default:"no title"}
--------- templates/footer.tpl --------
Notice we are passing the variable "title" when we include the header.tpl file.
You can pass as many variables as you want. The included file inherits all the
current template vars, plus any that are passed to it. The passed variables are
only available within the scope of the included file. Also notice the way the
$title variable is printed to the template. It uses a variable modifier called
"default". Printing {$title|default:"no title"} means that if the value of
$title is empty, the text "no title" will be printed instead of nothing.
IF/ELSEIF/ELSE
--------------
This syntax is very straightforward. The documention goes into depth on this
one, so you should be able to do just about anything you want to with it.
Example:
--------- templates/index.tpl --------
{include file="header.tpl" title="Home Page"}
{if $Name eq ""}
Hello, Noname!
{elseif $Name eq "Ned"}
Hello, Neddy!
{else}
Hello, {$Name}
{/if}
{$FirstName}, {$LastName}
{$Address}, {$Zipcode}
{include file="footer.tpl"}
SECTIONS (Dynamic Blocks)
-------------------------
Looping through arrays of data in Smarty is relatively simple, using the
{section} function. Two attributes are required: name and loop. name is the name
of the section, and loop is the name of the array that determines the number of
times the section will loop.
--------- index.php --------
assign("FirstName",array("Ned","Bart","Montgomery"));
$smarty->assign("LastName",array("Flanders","Simpson","Burns"));
$smarty->display("index.tpl");
?>
--------- templates/index.tpl --------
{include file="header.tpl" title="Home Page"}
{section name=people loop=$FirstName}
{%people.rownum%} {$people/FirstName} {$people/LastName}
{sectionelse}
There are no values to loop through.
{/section}
There were {%people.loop%} names in this list.
{include file="footer.tpl"}
Notice that when printing variables inside of the section, the section name must
be referenced in the name of the variable being displayed. This lets Smarty
understand that you want to print the value in the array postion indexed by the
current loop value. There are also internal template variables available within
the section that display the loop iteration and the total number of times the
section is looped. Also note the {sectionelse}. This would have been displayed
had the loop array $FirstName been empty.
You can also do complex nested sections, like so:
--------- index.php --------
assign("FirstName",array("Ned","Bart","Montgomery"));
$smarty->assign("LastName",array("Flanders","Simpson","Burns"));
$smarty->assign("ContactNames",array(
array("email","home","cell"),
array("email","home"),
array("email","home","fax")
));
$smarty->assign("ContactVals",array(
array("ned@simpsons.com","555-666-7777","555-444-3333"),
array("bart@simpsons.com","555-111-2222"),
array("monty@simpsons.com","555-888-9999","555-234-5678"),
));
$smarty->display("index.tpl");
?>
--------- templates/index.tpl --------
{include file="header.tpl" title="Home Page"}
{section name=people loop=$FirstName}
{%people.rownum%} {$people/FirstName} {$people/LastName}
{section name=contacts loop=$people/ContactNames}
{* for fun, lets bold every other row *}
{if %contacts.rownum% is even}{/if}
{$people/contacts/ContactNames}: {$people/contacts/ContactVals}
{if %contacts.rownum% is even}{/if}
{/section}
{sectionelse}
There are no values to loop through.
{/section}
There were {%people.loop%} names in this list.
{include file="footer.tpl"}
This should be enough to get your feet wet. Also, check out config file
variables, built-in functions, custom functions, variable modifiers, all sorts
of good stuff. Now go read the documentation, and Good Luck!