mirror of
https://github.com/smarty-php/smarty.git
synced 2025-08-03 09:54:27 +02:00
add QUICKSTART, update docs for default modifier
This commit is contained in:
mohrt
283
QUICKSTART
Normal file
283
QUICKSTART
Normal file
@@ -0,0 +1,283 @@
|
||||
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, what it is
|
||||
for 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.
|
||||
|
||||
OK, Let's get started.
|
||||
|
||||
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.
|
||||
|
||||
Ok, 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. You can change
|
||||
the ownership of this directory to your web server user, but we'll just
|
||||
change the permissions to 777 (drwxrwxrwx) to make it easy for this guide.
|
||||
|
||||
$> chmod 777 templates_c
|
||||
$> ls -l
|
||||
drwxrwxr-x 2 mohrt staff 512 Jan 18 14:18 configs/
|
||||
drwxrwxr-x 2 mohrt staff 512 Jan 18 14:18 templates/
|
||||
drwxrwxrwx 2 mohrt staff 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","Fred");
|
||||
$smarty->display("./templates/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, Fred!" 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, Fred!" 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 site, 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 are very similar to the ways you see other
|
||||
template engines assign them. Example:
|
||||
|
||||
|
||||
--------- index.php --------
|
||||
<?php
|
||||
require("Smarty.class.php");
|
||||
$smarty = new Smarty;
|
||||
$smarty->assign("Name","Fred");
|
||||
$smarty->assign(array(
|
||||
"FirstName" => "Fred",
|
||||
"LastName" => "Flanders",
|
||||
"Address" => "Springfield"
|
||||
));
|
||||
$zipcode = "55555";
|
||||
$smarty->assign("Zipcode",$zipcode);
|
||||
$smarty->display("./templates/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 single fasion, 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","Fred");
|
||||
$smarty->assign(array(
|
||||
"FirstName" => "Fred",
|
||||
"LastName" => "Flanders",
|
||||
"Address" => "Springfield"
|
||||
));
|
||||
$zipcode = "55555";
|
||||
$smarty->assign("Zipcode",$zipcode);
|
||||
$smarty->display("./templates/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:"Home Page"}</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:"Home Page"} means that if the value of
|
||||
$title is empty, the text "Home Page" will be printed instead of nothing.
|
||||
|
||||
IF/ELSEIF/ELSE
|
||||
--------------
|
||||
|
||||
This systax is very straight forward. 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 "Fred"}
|
||||
Hello, Frederick!<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("Fred","Bart","Montgomery"));
|
||||
$smarty->assign("LastName",array("Flanders","Simpson","Burns"));
|
||||
$smarty->display("./templates/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("Fred","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("fred@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("./templates/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!
|
||||
16
doc.sgm
16
doc.sgm
@@ -1521,6 +1521,14 @@ OUTPUT:
|
||||
|
||||
24.02
|
||||
|
||||
{* print "Home Page" if $title is empty *}
|
||||
{$title|default:"Home Page"}
|
||||
|
||||
OUTPUT:
|
||||
|
||||
Home Page
|
||||
|
||||
|
||||
</programlisting>
|
||||
</example>
|
||||
<para>
|
||||
@@ -1631,6 +1639,14 @@ is the first week that has at least 4 days in the current year, and with Monday
|
||||
</example>
|
||||
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>default</title>
|
||||
<para>
|
||||
This is used to set a default value for a variable. If the variable
|
||||
is empty or unset, the given default value is printed instead.
|
||||
Default takes one argument, the value to use as the default value.
|
||||
</para>
|
||||
</sect2>
|
||||
<sect2>
|
||||
<title>escape</title>
|
||||
<para>
|
||||
|
||||
Reference in New Issue
Block a user