mirror of
https://github.com/smarty-php/smarty.git
synced 2025-11-02 13:21:36 +01:00
369 lines
12 KiB
Plaintext
369 lines
12 KiB
Plaintext
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 some files: Smarty.class.php,
|
|
Smarty_Compiler.class.php, Config_File.class.php and a "plugins" directory. You
|
|
will need all 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 SMARTY_DIR path ends with a slash!
|
|
|
|
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:nobody", Mac OS X uses "www:www") 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 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 position 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!
|