mirror of
https://github.com/smarty-php/smarty.git
synced 2025-11-01 21:01:37 +01:00
300 lines
9.9 KiB
Plaintext
300 lines
9.9 KiB
Plaintext
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 three class files: Smarty.class.php,
|
|
Smarty.addons.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 --------
|
|
<?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.
|
|
|
|
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 touch 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 --------
|
|
<?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. 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}
|
|
{%people.rownum%} {$people/FirstName} {$people/LastName}<br>
|
|
{sectionelse}
|
|
There are no values to loop through.
|
|
{/section}
|
|
<p>
|
|
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 --------
|
|
<?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}
|
|
{%people.rownum%} {$people/FirstName} {$people/LastName}<br>
|
|
{section name=contacts loop=$people/ContactNames}
|
|
{* for fun, lets bold every other row *}
|
|
{if %contacts.rownum% is even}<b>{/if}
|
|
{$people/contacts/ContactNames}: {$people/contacts/ContactVals}<br>
|
|
{if %contacts.rownum% is even}</b>{/if}
|
|
{/section}
|
|
<br>
|
|
{sectionelse}
|
|
There are no values to loop through.
|
|
{/section}
|
|
<p>
|
|
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!
|