smarty/QUICKSTART

SMARTY QUICKSTART GUIDE
-----------------------

Welcome to the Smarty QUICKSTART guide. 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 four 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. Alternatively, you can set the SMARTY_DIR constant in your
application, and Smarty will use that directory as the path to the Smarty
class files. Be sure the path ends with a slash!

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/

Make sure the current directory and the path to PEAR.php are in your
include_path. Example php.ini entries:
(unix) include_path=".:/usr/local/lib/php"
(windows) include_path=".;\php\pear"
Also, windows users may have to change the filename from PEAR.php.in
to PEAR.php (named like this in some distributions?)

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 its template file. (Smarty template files are never
accessed directly from the browser, only the Smarty class accesses them.)


--------- index.php --------
<?php
require("Smarty.class.php");
$smarty = new Smarty;
$smarty->assign("Name","Ned");
$smarty->display("index.tpl");
?>


--------- templates/index.tpl --------
<HTML>
<TITLE>Hello</TITLE>
<BODY>
    Hello, {$Name}!
</BODY>
</HTML>


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. If your still having problems, ask a
question on the mailing list, which you can find in the FAQ.

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 take a look at a few
features of the template language.

ASSIGNING VARIABLES
-------------------

Assigning variables to the template is fairly straight forward. Example:


--------- index.php --------
<?php
require("Smarty.class.php");
$smarty = new Smarty;
$smarty->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 --------
<HTML>
<TITLE>Hello</TITLE>
<BODY>
    Hello, {$Name}!<br>
    {$FirstName}, {$LastName}<br>
    {$Address}, {$Zipcode}
</BODY>
</HTML>


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 --------
<?php
require("Smarty.class.php");
$smarty = new Smarty;
$smarty->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}!<br>
    {$FirstName}, {$LastName}<br>
    {$Address}, {$Zipcode}
{include file="footer.tpl"}

--------- templates/header.tpl --------
<HTML>
<TITLE>{$title|default:"no title"}</TITLE>
<BODY>

--------- templates/footer.tpl --------
</BODY>
</HTML>


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 (and any files it may
include.) 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!<br>
	{elseif $Name eq "Ned"}
		Hello, Neddy!<br>
	{else}
		Hello, {$Name}<br>
	{/if}
	
	{$FirstName}, {$LastName}<br>
	{$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 --------
<?php
require("Smarty.class.php");
$smarty = new Smarty;
$smarty->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}
        {$smarty.section.people.rownum} {$FirstName[people]} {$LastName[people]}<br>
    {sectionelse}
        There are no values to loop through.
    {/section}
    <p>
    There were {$smarty.section.people.loop} names in this list.
{include file="footer.tpl"}

Here we are introducing the {$smarty} variable, which is used to reference
values internal to the template. 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 if looped array $FirstName was
empty.

You can access keys of arrays with this syntax:

--------- index.php --------
<?php
require("Smarty.class.php");
$smarty = new Smarty;
$smarty->assign(array("ContactInfo" => array(
				array("FirstName" => "Ned","LastName" => "Flanders"),
				array("FirstName" => "Monty","LastName" => "Burns")
				)
			));
$smarty->display("index.tpl");
?>

--------- templates/index.tpl --------
{include file="header.tpl" title="Home Page"}
    {section name=people loop=$ContactInfo}
        {$ContactInfo[people].FirstName}
		{$ContactInfo[people].LastName}<br>
    {sectionelse}
        There are no values to loop through.
    {/section}
    <p>
    There were {$smarty.section.people.loop} names in this list.
{include file="footer.tpl"}


You can also do complex nested sections, like so:

--------- index.php --------
<?php
require("Smarty.class.php");
$smarty = new Smarty;
$smarty->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}
        {$smarty.section.people.rownum} {$FirstName[people]} {$LastName[people]}<br>
        {section name=contacts loop=$ContactNames[people]}
            {* for fun, lets bold every other row *}
            {if $smarty.section.contacts.rownum is even}<b>{/if}
                {$ContactNames[people][contacts]}: {$ContactVals[people][contacts]}<br>
            {if $smarty.section.contacts.rownum is even}</b>{/if}
        {/section}
        <br>
    {sectionelse}
        There are no values to loop through.
    {/section}
    <p>
    There were {$smarty.section.people.loop} names in this list.
{include file="footer.tpl"}


FOREACH
-------

There is also an alternative way to loop through associative arrays that may be
a bit easier for you, especially if you only need to loop over one variable.

Here's an example that works with the default index.php that comes with Smarty:

{foreach name=outer item=contact from=$contacts}
  {foreach key=key item=item from=$contact}
    {$smarty.foreach.outer.iteration}. contact {$key}: {$item}
  {/foreach}
{foreachelse}
  no contacts
{/foreach}

Possible attributes:

from: the array you are looping through
item: the name of the variable that is the current element
key:  the name of the variable that is the current key (optional)
name: the name of the of foreach (optional)

The 'name' has to be used if you want to refer to any of the foreach
properties.

Properties (if 'name' is used):

name: the name of foreach
iteration: current iteration
total: total number of iterations
first: if it's first iteration
last: it it's last iteration
show: if foreach was shown at all

Here's another neat example, dumps all properties of foreach:

{foreach name=outer item=contact from=$contacts}
  {foreach key=key item=item from=$smarty.foreach.outer}
    {$key}: {$item}
  {/foreach}
{/foreach}


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, join the mailing list and have
fun!