mirror of
https://github.com/smarty-php/smarty.git
synced 2025-11-03 05:41:37 +01:00
1983 lines
60 KiB
Plaintext
1983 lines
60 KiB
Plaintext
<!dOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
|
|
<book>
|
|
<bookinfo>
|
|
<title>Smarty - the compiling PHP template engine</title>
|
|
<author>
|
|
<firstname>Monte</firstname><surname>Ohrt</surname>
|
|
<affiliation>
|
|
<address><email>monte@ispi.net</email></address>
|
|
</affiliation>
|
|
</author>
|
|
<author>
|
|
<firstname>Andrei</firstname><surname>Zmievski</surname>
|
|
<affiliation>
|
|
<address><email>andrei@ispi.net</email></address>
|
|
</affiliation>
|
|
</author>
|
|
<edition>Version 1.2.1</edition>
|
|
<copyright><year>2001</year><holder>ispi of Lincoln, Inc.</holder></copyright>
|
|
</bookinfo>
|
|
<chapter>
|
|
<title>Overview</title>
|
|
<para>
|
|
It is undoubtedly one of the most asked questions on the PHP mailing
|
|
lists: how do I make my PHP scripts independent of the layout? While
|
|
PHP is billed as "HTML embedded scripting language", after writing a
|
|
couple of projects that mixed PHP and HTML freely one comes up with the
|
|
idea that separation of form and content is a Good Thing [TM]. In
|
|
addition, in many companies the roles of layout designer and programmer
|
|
are separate. Consequently, the search for a templating solution
|
|
ensues.
|
|
</para>
|
|
<para>
|
|
In our company for example, the development of an application goes on
|
|
as follows: After the requirements docs are done, the interface
|
|
designer makes mockups of the interface and gives them to the
|
|
programmer. The programmer implements business logic in PHP and uses
|
|
interface mockups to create skeleton templates. The project is then
|
|
handed off to the HTML designer/web page layout person who brings the
|
|
templates up to their full glory. The project may go back and forth
|
|
between programming/HTML a couple of times. Thus, it's important to
|
|
have good template support because programmers don't want anything to
|
|
do with HTML and don't want HTML designers mucking around with PHP
|
|
code. Designers need support for config files, dynamic blocks and other
|
|
stuff, but they don't want to have to deal with intricacies of the PHP
|
|
programming language.
|
|
</para>
|
|
<para>
|
|
Looking at many templating solutions available for PHP today, most of
|
|
them provide a rudimentary way of substituting variables into templates
|
|
and do a limited form of dynamic block functionality. But our needs
|
|
required a bit more than that. We didn't want programmers to be dealing
|
|
with HTML layout at ALL, but this was almost inevitable. For instance,
|
|
if a designer wanted background colors to alternate on dynamic blocks,
|
|
this had to be worked out with the programmer in advance. We also
|
|
needed designers to be able to use their own configuration files, and
|
|
pull variables from them into the templates. The list goes on.
|
|
</para>
|
|
<para>
|
|
We started out writing out a spec for a template engine about a year
|
|
ago. After finishing the spec, we began to work on a template engine
|
|
written in C that would hopefully be accepted for inclusion with PHP.
|
|
Not only did we run into many complicated technical barriers, but there
|
|
was also much heated debate about exactly what a template engine should
|
|
and should not do. From this experience, we decided that the template
|
|
engine should be written in PHP as a class, for anyone to use as they
|
|
see fit. So we wrote an engine that did just that and
|
|
<emphasis>SmartTemplate</emphasis> came into existence (note: this
|
|
class was never submitted to the public). It was a class that did
|
|
almost everything we wanted: regular variable substitution, supported
|
|
including other templates, integration with config files, embedding PHP
|
|
code, limited 'if' statement functionality and much more robust dynamic
|
|
blocks which could be multiply nested. It did all this with regular
|
|
expressions and the code turned out to be rather, shall we say,
|
|
impenetrable. It was also noticably slow in large applications from all
|
|
the parsing and regular expression work it had to do on each
|
|
invocation. The biggest problem from a programmer's point of view was
|
|
all the necessary work in the PHP script to setup and process templates
|
|
and dynamic blocks. How do we make this easier?
|
|
</para>
|
|
<para>
|
|
Then came the vision of what ultimately became Smarty. We know how fast
|
|
PHP code is without the overhead of template parsing. We also know how
|
|
meticulous and overbearing the PHP language may look to the average
|
|
designer, and this could be masked with a much simpler templating
|
|
syntax. So what if we combined the two strengths? Thus, Smarty was
|
|
born...
|
|
</para>
|
|
<sect1><title>What is Smarty?</title>
|
|
<para>
|
|
Smarty is a template engine for PHP. One of the unique aspects about
|
|
Smarty that sets it apart from other templating solutions is that it
|
|
compiles the templates into native PHP scripts upon the first
|
|
invocation. After that, it merely executes the compiled PHP scripts.
|
|
Therefore, there is no costly template file parsing for each request.
|
|
</para>
|
|
<para>
|
|
Some of Smarty's features:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>It is extremely fast.</para></listitem>
|
|
<listitem><para>It is efficient since the PHP parser does the
|
|
dirty work.</para></listitem>
|
|
<listitem><para>No template parsing overhead, only compiles once.</para></listitem>
|
|
<listitem><para>It is smart about recompiling only the template
|
|
files that have changed.</para></listitem>
|
|
<listitem><para>You can make <link linkend="custom.functions">custom
|
|
functions</link> and custom <link linkend="variable.modifiers">variable
|
|
modifiers</link>, so the template language is extremely extensible.</para></listitem>
|
|
<listitem><para>Configurable template delimiter tag syntax, so you can use
|
|
{}, {{}}, <!--{}-->, or whatever you like.</para></listitem>
|
|
<listitem><para>The if/elseif/else/endif constructs are passed to the
|
|
PHP parser, so the if expression syntax can be as simple or as complex
|
|
as you like.</para></listitem>
|
|
<listitem><para>Unlimited nesting of sections, ifs, etc. allowed.</para></listitem>
|
|
<listitem><para>It is possible to embed PHP code right in your template files,
|
|
although this may not be needed (nor recommended)
|
|
since the engine is so customizable.</para></listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
<sect1>
|
|
<title>How Smarty works</title>
|
|
<sect2><title>Compiling</title>
|
|
<para>
|
|
Smarty compiles the templates into native PHP code on-the-fly. The actual
|
|
PHP scripts that are generated are created implicitly, so theoretically you
|
|
should never have to worry about touching these files, or even know of their
|
|
existence. The exception to this is debugging Smarty template syntax errors,
|
|
discussed later in this document.
|
|
</para>
|
|
</sect2>
|
|
<sect2><title>Caching</title>
|
|
<para>
|
|
Our initial intention was to build caching into Smarty. However,
|
|
since the template engine is actually executing PHP scripts instead of
|
|
parsing template files, the need for a cache was dramatically reduced.
|
|
We may implement this in a future version of Smarty as the need arises.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<chapter>
|
|
<title>Installation</title>
|
|
<sect1>
|
|
<title>Requirements</title>
|
|
<para>
|
|
Smarty requires PHP 4.0.4pl1 or later. See the
|
|
<link linkend="bugs">BUGS</link> section for caveats.
|
|
</para>
|
|
</sect1>
|
|
<sect1>
|
|
<title>Installing Smarty</title>
|
|
<para>
|
|
Installing Smarty is fairly straightforward, there is just one thing
|
|
you must be aware of. Remember that Smarty creates compiled versions of
|
|
the template code. This usually means allowing user "nobody" (or
|
|
whomever the web server runs as) to have permission to write the files.
|
|
Each installation of a Smarty application minimally needs a templates
|
|
directory and a compiled templates directory. If you use configuration
|
|
files you will also need a directory for those. By default these are
|
|
named "templates", and "templates_c" and "configs" respectively.
|
|
</para>
|
|
<para>
|
|
Copy the Smarty.class.php, Smarty.addons.php and Config_File.class.php
|
|
scripts to a directory that is in your PHP include_path. NOTE: PHP will
|
|
try to create a directory alongside the executing script called
|
|
"templates_c". Be sure that directory permissions allow this to happen.
|
|
You will see PHP error messages if this fails. You can also create the
|
|
directory yourself before hand, and change the file ownership
|
|
accordingly. See below.
|
|
</para>
|
|
<example>
|
|
<title>Example of installing Smarty</title>
|
|
<programlisting>
|
|
|
|
# be sure you are in the web server document tree
|
|
# this assumes your web server runs as user "nobody"
|
|
# and you are in a un*x environment
|
|
gtar -zxvf Smarty-1.0.tar.gz
|
|
mkdir templates_c
|
|
chown nobody:nobody templates_c
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
Next, try running the index.php script from your web browser.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
<chapter>
|
|
<title>Setting up Smarty</title>
|
|
<para>
|
|
There are several variables that are at the top of the Smarty.class.php
|
|
file. You can usually get away with leaving these at their default
|
|
settings. This is a list of them and what each one does.
|
|
</para>
|
|
<sect1>
|
|
<title>Configuration variables</title>
|
|
<para></para>
|
|
<sect2>
|
|
<title>$compile_check</title>
|
|
<para>
|
|
Upon each invocation of the PHP application, Smarty recursively
|
|
traverses the template directory and its subdirectories and
|
|
searches for all the files with the template extension that
|
|
have changed (later time stamp) since the last time they were
|
|
compiled. For each one that has changed, it recompiles that
|
|
template. By default this variable is set to true. The compile
|
|
check has very minimal impact on the application performance.
|
|
However, once an application is put into production and it is
|
|
initially compiled, the compile_check step is no longer needed.
|
|
You may set this to "false" *after* the initial compile. Then
|
|
Smarty will no longer check for changed template files. Note
|
|
that if you change this to "false" and a template file is
|
|
changed, you will *not* see the change since the template will
|
|
not get recompiled. Set it to "true", invoke the application,
|
|
then set it back to "false".
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="template.dir">
|
|
<title>$template_dir</title>
|
|
<para>
|
|
This is the name of the directory where template files are located.
|
|
By default this is "./templates".
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>$compile_dir</title>
|
|
<para>
|
|
This is the name of the directory where compiled templates are
|
|
located. By default this is "./templates_c". NOTE: this was
|
|
added to Smarty version 1.2.1.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>$compile_dir_ext</title>
|
|
<para>
|
|
This is the extension used for the name of the directory where
|
|
compiled templates are located. By default this is "_c".
|
|
Therefore if your template directory is named "templates", then
|
|
the compiled templates directory will be named "templates_c".
|
|
NOTE: this was removed from Smarty version 1.2.1.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>$tpl_file_ext</title>
|
|
<para>
|
|
This is the extention used for template files. By default this
|
|
is ".tpl". All other files in the template directory are
|
|
ignored.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>$allow_php</title>
|
|
<para>
|
|
Whether or not to allow PHP code in the templates. If set to
|
|
false, PHP code is escaped and not interpreted. Embedding PHP
|
|
code into templates is highly discouraged. Use <link
|
|
linkend="custom.functions">custom functions</link> or <link
|
|
linkend="variable.modifiers">modifiers</link> instead. Default
|
|
is "false".
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>$left_delimiter</title>
|
|
<para>
|
|
This is the left delimiter used by the template language. Default is "{".
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>$right_delimiter</title>
|
|
<para>
|
|
This is the right delimiter used by the template language. Default is "}".
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>$config_dir</title>
|
|
<para>
|
|
This is the directory used to store config files used in the templates.
|
|
Default is "configs".
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>$custom_funcs</title>
|
|
<para>
|
|
This is a mapping of the names of <link
|
|
linkend="custom.functions">custom functions</link> in the template to
|
|
the names of functions in PHP. These are usually kept in Smarty.addons.php.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>$custom_mods</title>
|
|
<para>
|
|
This is a mapping of the names of variable
|
|
<link linkend="variable.modifiers">modifiers</link> in the template to
|
|
the names of functions in PHP. These are usually kept in Smarty.addons.php.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>$global_assign</title>
|
|
<para>
|
|
This is a list of variables that are always implicitly assigned to the
|
|
template engine. This is usually handy for making global variables or server
|
|
variables available to the template without having to manually assign them to
|
|
the template every time.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<chapter>
|
|
<title>Smarty API</title>
|
|
<para>
|
|
These functions are used in the PHP portion of your application.
|
|
</para>
|
|
<sect1>
|
|
<title>Smarty API Functions</title>
|
|
<sect2>
|
|
<title>assign</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>assign</function></funcdef>
|
|
<paramdef>mixed <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>assign</function></funcdef>
|
|
<paramdef>string <parameter>varname</parameter></paramdef>
|
|
<paramdef>mixed <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This is used to assign values to the templates. This is usually
|
|
data gathered from database queries or other sources of data.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>append</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>append</function></funcdef>
|
|
<paramdef>mixed <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>append</function></funcdef>
|
|
<paramdef>string <parameter>varname</parameter></paramdef>
|
|
<paramdef>mixed <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This is used to append data to existing variables in the template.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>clear_assign</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>clear_assign</function></funcdef>
|
|
<paramdef>string <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This clears the value of an assigned variable.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>clear_all_assign</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>clear_all_assign</function></funcdef>
|
|
<paramdef><parameter></parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This clears the values of all assigned variables.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>get_template_vars</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>get_template_vars</function></funcdef>
|
|
<paramdef><parameter></parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This gets an array of the currently assigned template vars.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>display</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>display</function></funcdef>
|
|
<paramdef>string <parameter>template</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This displays the template. Supply a path relative to the
|
|
<link linkend="template.dir">template directory</link>
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>fetch</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>fetch</function></funcdef>
|
|
<paramdef>string <parameter>template</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This returns the template output. Supply a path relative to the
|
|
<link linkend="template.dir">template directory</link>
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Using Smarty API</title>
|
|
<example>
|
|
<title>Example use of Smarty API</title>
|
|
<programlisting>
|
|
|
|
include("Smarty.class.php");
|
|
$smarty = new Smarty;
|
|
|
|
// dummy up some data
|
|
$address = "245 N 50th";
|
|
$db_data = array(
|
|
"City" => "Lincoln",
|
|
"State" => "Nebraska",
|
|
"Zip" = > "68502"
|
|
);
|
|
|
|
$smarty->assign("Name","Fred");
|
|
$smarty->assign("Address",$address);
|
|
$smarty->assign($db_data);
|
|
|
|
// display the output
|
|
$smarty->display("index.tpl");
|
|
|
|
// alternatively capture the output
|
|
$output = $smarty->fetch("index.tpl");
|
|
</programlisting>
|
|
</example>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<chapter>
|
|
<title>Smarty Templates</title>
|
|
<para>
|
|
The templates are the heart of Smarty. These are the files that the designers
|
|
work with. They're basically pages made up of static content interspersed with
|
|
template markup tags. These tags are placeholders for variables or blocks of logic.
|
|
</para>
|
|
<sect1>
|
|
<title>Syntax</title>
|
|
<para>
|
|
For these examples, we will assume that you are using the default
|
|
template tag delimiters, which are "{" and "}". In Smarty, all content
|
|
outside of delimiter tags is displayed as static content, or unchanged.
|
|
When Smarty encounters template tags {}, it attempts to interpret what is
|
|
between the tags, and displays the appropriate output in place of them.
|
|
</para>
|
|
<sect2>
|
|
<title>Variables</title>
|
|
<para>
|
|
There are three basic types of variables in Smarty, each with their
|
|
own unique syntax.
|
|
</para>
|
|
<sect3>
|
|
<title>Variables assigned from PHP</title>
|
|
<para>
|
|
Variables that are assigned from PHP are displayed by preceeding
|
|
them with a dollar sign ($) and enclosing the variable in delimiters
|
|
like so: {$varname}
|
|
</para>
|
|
<example>
|
|
|
|
<title>displaying assigned variables</title>
|
|
<programlisting>
|
|
|
|
Hello {$firstname}, glad to see you could make it.
|
|
<p>
|
|
Your last login was on {$lastLoginDate}.
|
|
|
|
OUTPUT:
|
|
|
|
Hello Doug, glad to see you could make it.
|
|
<p>
|
|
Your last login was on January 11th, 2001.
|
|
</programlisting>
|
|
</example>
|
|
</sect3>
|
|
|
|
<sect3>
|
|
<title>Associative arrays</title>
|
|
<para>
|
|
You can also print variables that are assigned as associative
|
|
arrays from PHP by supplying the key value with the array name.
|
|
</para>
|
|
<example>
|
|
<title>displaying assigned associative array variables</title>
|
|
<programlisting>
|
|
|
|
{$Contacts.fax}<br>
|
|
{$Contacts.email}<br>
|
|
{* you can print arrays of arrays as well *}
|
|
{$Contacts.phone.home}<br>
|
|
{$Contacts.phone.cell}<br>
|
|
|
|
OUTPUT:
|
|
|
|
555-222-9876<br>
|
|
zaphod@slartibartfast.com<br>
|
|
555-444-3333<br>
|
|
555-111-1234<br>
|
|
|
|
|
|
|
|
</programlisting>
|
|
</example>
|
|
</sect3>
|
|
|
|
|
|
<sect3>
|
|
<title>Variables passed from config files</title>
|
|
<para>
|
|
Variables that are passed in from config files are displayed by enclosing
|
|
them with hash marks (#) and enclosing the variable in delimiters
|
|
like so: {#varname#}
|
|
</para>
|
|
<example>
|
|
|
|
|
|
<title>displaying config variables</title>
|
|
<programlisting>
|
|
|
|
<html>
|
|
<title>{#pageTitle#}</title>
|
|
<body bgcolor="{#bodyBgColor#}">
|
|
<table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}">
|
|
<tr bgcolor="{#rowBgColor#}">
|
|
<td>First</td>
|
|
<td>Last</td>
|
|
<td>Address</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
Config file variables cannot be displayed until
|
|
after they are loaded in from a config file. This procedure is
|
|
explained later in this document under
|
|
<link linkend="builtin.functions.configload">config_load</link>.
|
|
</para>
|
|
</sect3>
|
|
<sect3>
|
|
<title>Variables internal to template</title>
|
|
<para>
|
|
Variables that are internal to the templates are displayed by enclosing
|
|
them with percent signs (%) and enclosing the variable in delimiters
|
|
like so: {%varname%} So far, section properties are the only internal
|
|
variables used in Smarty, which can be found later in this document under
|
|
<link linkend="builtin.functions.section">section</link>.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Functions</title>
|
|
<para>
|
|
Functions are processed and displayed by enclosing the function and its
|
|
attributes into delimiters like so: {funcname attr1="val" attr2="val"}
|
|
</para>
|
|
<example>
|
|
<title>function syntax</title>
|
|
<programlisting>
|
|
|
|
{config_load file="colors.conf"}
|
|
|
|
{include file="header.tpl"}
|
|
|
|
{if $name eq "Fred"}
|
|
You are not allowed here
|
|
{else}
|
|
Welcome, <font color="{#fontColor#}">{$name}!</font>
|
|
{/if}
|
|
|
|
{include file="footer.tpl"}
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
Both built-in functions and custom functions have the same syntax
|
|
in the templates. Built-in functions are the inner workings of
|
|
Smarty, such as {if}, {section} and {strip}. They cannot be
|
|
modified. Custom functions are located in the Smarty.addons.class
|
|
file. They can be modified to your liking, or add new ones.
|
|
{html_options} and {html_select_date} are examples of custom
|
|
functions.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Attributes</title>
|
|
<para>
|
|
Attributes to functions are much like HTML attributes. Static
|
|
values don't have to be enclosed in quotes, but it is recommended
|
|
for literal strings. If not quoted, you may use a syntax that Smarty may confuse
|
|
with another function, such as a boolean value. Variables may
|
|
also be used, and should not be in quotes.
|
|
</para>
|
|
<example>
|
|
<title>function attribute syntax</title>
|
|
<programlisting>
|
|
|
|
{include file="header.tpl"}
|
|
|
|
{include file=$includeFile}
|
|
|
|
{include file=#includeFile#}
|
|
|
|
<SELECT name=company>
|
|
{html_options values=$vals selected=$selected output=$output}
|
|
</SELECT>
|
|
</programlisting>
|
|
</example>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Comments</title>
|
|
<para>
|
|
Template comments are surrounded by asterisks, and that is surrounded
|
|
by the delimiter tags like so: {* this is a comment *}
|
|
Smarty comments are not displayed in the final output of the template.
|
|
They are used mainly for making the templates more understandable.
|
|
</para>
|
|
<example>
|
|
<title>Comments</title>
|
|
<programlisting>
|
|
|
|
{* Smarty *}
|
|
|
|
{* include the header file here *}
|
|
{include file="header.tpl"}
|
|
|
|
{include file=$includeFile}
|
|
|
|
{include file=#includeFile#}
|
|
|
|
{* display dropdown lists *}
|
|
<SELECT name=company>
|
|
{html_options values=$vals selected=$selected output=$output}
|
|
</SELECT>
|
|
</programlisting>
|
|
</example>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="configfiles">
|
|
<title>Config Files</title>
|
|
<para>
|
|
Config files are handy for designers to manage global
|
|
template variables from one file. One example is template colors.
|
|
Normally if you wanted to change the color scheme of an application,
|
|
you would have to go through each and every template file
|
|
and change the colors. With a config file, the colors can
|
|
be kept in one place, and only one file needs to be updated.
|
|
Note that to use config files, you must include the Config_File.class.php
|
|
In your PHP include path. Config_File.class.php comes bundled with
|
|
Smarty. Smarty will implicitly include the file if you
|
|
don't already include it in your application.
|
|
</para>
|
|
<example>
|
|
<title>Example of config file syntax</title>
|
|
<programlisting>
|
|
|
|
# global variables
|
|
pageTitle = "Main Menu"
|
|
bodyBgColor = #000000
|
|
tableBgColor = #000000
|
|
rowBgColor = #00ff00
|
|
|
|
[Customer]
|
|
pageTitle = "Customer Info"
|
|
|
|
[Login]
|
|
pageTitle = "Login"
|
|
focus = "username"
|
|
Intro = """This is a value that spans more
|
|
than one line. you must enclose
|
|
it in triple quotes."""
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
Values of config file variables can be in quotes, but not necessary.
|
|
You can use either single or double quotes. If you have a value that
|
|
spans more than one line, enclose the entire value with triple quotes
|
|
("""). You can put comments into config files by any syntax that is
|
|
not a valid config file syntax. We recommend using a hashmark (#) at the
|
|
beginning of the line.
|
|
</para>
|
|
<para>
|
|
This config file example has two sections. Section names are enclosed
|
|
in brackets []. The four variables at the top are global
|
|
variables, or variables not within a section. These variables are
|
|
always loaded from the config file.
|
|
If a particular section is loaded, then the global variables and the
|
|
variables from that section are loaded. If a variable exists both as
|
|
a global and in a section, the section variable is used. If you name two
|
|
variables the same within a section, the last one will be used.
|
|
</para>
|
|
<para>
|
|
Config files are loaded into templates with the built-in function
|
|
called <link linkend="builtin.functions.configload">config_load</link>.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="builtin.functions">
|
|
<title>Built-in Functions</title>
|
|
<para>
|
|
Smarty comes with several built-in functions. Built-in functions
|
|
are integral to the template language. You cannot create custom
|
|
functions with the same names, nor can you modify built-in functions.
|
|
</para>
|
|
<sect2 id="builtin.functions.configload">
|
|
<title>config_load</title>
|
|
<para>
|
|
This function is used for loading in variables from a
|
|
configuration file into the template. You must have the Config_file.class.php
|
|
file somewhere in your PHP include path for config_load to work properly.
|
|
See <link linkend="configfiles">Config Files</link> for more info.
|
|
</para>
|
|
<example>
|
|
<title>function config_load</title>
|
|
<programlisting>
|
|
|
|
{config_load file="colors.conf"}
|
|
|
|
<html>
|
|
<title>{#pageTitle#}</title>
|
|
<body bgcolor="{#bodyBgColor#}">
|
|
<table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}">
|
|
<tr bgcolor="{#rowBgColor#}">
|
|
<td>First</td>
|
|
<td>Last</td>
|
|
<td>Address</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
Config files may also contain sections. You can load
|
|
variables from within a section with the added attribute
|
|
"section".
|
|
</para>
|
|
<example>
|
|
<title>function config_load with section</title>
|
|
<programlisting>
|
|
|
|
{config_load file="colors.conf" section="Customer"}
|
|
|
|
<html>
|
|
<title>{#pageTitle#}</title>
|
|
<body bgcolor="{#bodyBgColor#}">
|
|
<table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}">
|
|
<tr bgcolor="{#rowBgColor#}">
|
|
<td>First</td>
|
|
<td>Last</td>
|
|
<td>Address</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|
|
</programlisting>
|
|
</example>
|
|
</sect2>
|
|
<sect2>
|
|
<title>include</title>
|
|
<para>
|
|
Include tags are used for including other templates into
|
|
the current template. When a template is included, it
|
|
inherits all the variables available to the current template.
|
|
The include tag must have the attribute "file", which
|
|
contains the path to the included template file relative
|
|
to the template directory.
|
|
</para>
|
|
<example>
|
|
<title>function include</title>
|
|
<programlisting>
|
|
|
|
{include file="header.tpl"}
|
|
|
|
{* body of template goes here *}
|
|
|
|
{include file="footer.tpl"}
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
You can also pass variables to included templates as attributes.
|
|
These will be passed to the template along with the current
|
|
template variables. Attribute variables override template
|
|
variables, in the case they are named alike. You can
|
|
pass either static values or variables to included templates
|
|
(although it doesn't make much sense to pass anything other than
|
|
static values since variables are inherited anyways).
|
|
</para>
|
|
<example>
|
|
<title>function include passing variables</title>
|
|
<programlisting>
|
|
|
|
{include file="header.tpl" title="Main Menu" table_bgcolor="#c0c0c0"}
|
|
|
|
{* body of template goes here *}
|
|
|
|
{include file="footer.tpl" logo="http://my.domain.com/logo.gif"}
|
|
|
|
</programlisting>
|
|
</example>
|
|
</sect2>
|
|
<sect2>
|
|
<title>insert</title>
|
|
<para>
|
|
The insert tag in Smarty serves a special purpose. You may
|
|
run into the situation where it is impossible to pass data to a template
|
|
before the template is executed because there is info in the template
|
|
needed to aquire the data, kind of a catch 22. The insert tag is a way
|
|
to callback a function in PHP during runtime of the template. (This is much
|
|
like the functionality of Server Side Includes in a static html page.)
|
|
</para>
|
|
<para>
|
|
Let's say you have a template with a banner slot at the top of the page. The
|
|
banner can contain any mixture of HTML, images, flash, etc. so we can't just
|
|
use a static link here. In comes the insert tag: the template
|
|
knows #banner_location_id# and #site_id# values (gathered from a config file),
|
|
and needs to call a function to get the banner's contents.
|
|
</para>
|
|
<example>
|
|
<title>function insert</title>
|
|
<programlisting>
|
|
|
|
{* example of fetching a banner *}
|
|
{insert name="getBanner" lid=#banner_location_id# sid=#site_id#}
|
|
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
In this example, we are using the name "getBanner" and passing the
|
|
parameters #banner_location_id# and #site_id#. Smarty will look
|
|
for a function named insert_getBanner() in your PHP application, passing
|
|
the values of #banner_location_id# and #site_id# as the first argument
|
|
in an associative array. All insert function names in
|
|
your application must be prepended with "insert_" to remedy possible
|
|
function name-space conflicts. Your insert_getBanner() function should
|
|
do something with the passed values and return the results. These results
|
|
are then displayed in the template in place of the insert tag.
|
|
In this example, Smarty would call this function:
|
|
insert_getBanner(array("banner_id" => "12345","page_id" => "67890"));
|
|
and display the returned results in place of the insert tag.
|
|
</para>
|
|
<para>
|
|
Another thing to keep in mind for the insert tag is caching. Smarty does not
|
|
currently support caching but if that is eventually implemented, insert
|
|
tags will not be cached. They will run dynamically every time the page
|
|
is created. This works good for things like banners, polls, live weather,
|
|
user feedback areas, etc.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>if,elseif,else</title>
|
|
<para>
|
|
if statements in Smarty have much the same flexibility as php if statements,
|
|
with a few added features for the template engine.
|
|
Every if must be paired with /if. else and elseif are also permitted.
|
|
"eq", "ne","neq", "gt", "lt", "lte", "le", "gte" "ge","is even","is odd",
|
|
"is not even","is not odd","not","mod","div by","even by","odd by","==","!=",">",
|
|
"<","<=",">=" are all valid conditional qualifiers.
|
|
</para>
|
|
<example>
|
|
<title>if statements</title>
|
|
<programlisting>
|
|
|
|
{if $name eq "Fred"}
|
|
Welcome Sir.
|
|
{elseif $name eq "Wilma"}
|
|
Welcome Ma'am.
|
|
{else}
|
|
Welcome, whatever you are.
|
|
{/if}
|
|
|
|
{* an example with "or" logic *}
|
|
{if $name eq "Fred" or $name eq "Wilma"}
|
|
...
|
|
{/if}
|
|
|
|
{* parenthesis are allowed *}
|
|
{if ( $amount < 0 or $amount > 1000 ) and $volume >= #minVolAmt#}
|
|
...
|
|
{/if}
|
|
|
|
{* you can also imbed php function calls *}
|
|
{if count($var) gt 0}
|
|
...
|
|
{/if}
|
|
|
|
{* test if values are even or odd *}
|
|
{if $var is even}
|
|
...
|
|
{/if}
|
|
{if $var is odd}
|
|
...
|
|
{/if}
|
|
{if $var is not odd}
|
|
...
|
|
{/if}
|
|
|
|
{* test if var is divisible by 4 *}
|
|
{if $var is div by 4}
|
|
...
|
|
{/if}
|
|
|
|
{* same as previous example *}
|
|
{if $var is mod 4}
|
|
...
|
|
{/if}
|
|
|
|
{* test if var is even, grouped by two. i.e.,
|
|
0=even, 1=even, 2=odd, 3=odd, 4=even, 5=even, etc. *}
|
|
{if $var is even by 2}
|
|
...
|
|
{/if}
|
|
|
|
{* 0=even, 1=even, 2=even, 3=odd, 4=odd, 5=odd, etc. *}
|
|
{if $var is even by 3}
|
|
...
|
|
{/if}
|
|
|
|
</programlisting>
|
|
</example>
|
|
</sect2>
|
|
<sect2>
|
|
<title>ldelim,rdelim</title>
|
|
<para>
|
|
ldelim and rdelim are used for displaying the literal delimiter, in
|
|
our case "{" or "}". The template engine always tries to interpret
|
|
delimiters, so this is the way around that.
|
|
</para>
|
|
<example>
|
|
<title>ldelim, rdelim</title>
|
|
<programlisting>
|
|
|
|
{* this will print literal delimiters out of the template *}
|
|
|
|
{ldelim}funcname{rdelim} is how functions look in Smarty!
|
|
|
|
|
|
OUTPUT:
|
|
|
|
{funcname} is how functions look in Smarty!
|
|
</programlisting>
|
|
</example>
|
|
</sect2>
|
|
<sect2>
|
|
<title>literal</title>
|
|
<para>
|
|
Literal tags allow a block of data to be taken literally,
|
|
not being interpreted by the Smarty engine. This is handy
|
|
for things like javascript sections, where there maybe
|
|
curly braces and such things that would confuse the template
|
|
parser. Anything within {literal}{/literal} tags is not
|
|
interpreted, but displayed as-is.
|
|
</para>
|
|
<example>
|
|
<title>literal tags</title>
|
|
<programlisting>
|
|
|
|
{literal}
|
|
<script language=javascript>
|
|
|
|
<!--
|
|
function isblank(field) {
|
|
if (field.value == '')
|
|
{ return false; }
|
|
else
|
|
{
|
|
document.loginform.submit();
|
|
return true;
|
|
}
|
|
}
|
|
// -->
|
|
|
|
</script>
|
|
{/literal}
|
|
</programlisting>
|
|
</example>
|
|
</sect2>
|
|
<sect2 id="builtin.functions.section">
|
|
<title>section,sectionelse</title>
|
|
<para>
|
|
Template sections are used for looping over arrays of data.
|
|
All section tags must be paired with /section tags.
|
|
Required parameters are "name" and "loop". The name of the
|
|
section can be anything you like, made up of letters, numbers
|
|
and underscores. Sections can be nested, and the nested
|
|
section names must be unique from each other. The loop variable
|
|
determines the number of times the section will loop.
|
|
When printing a variable within a section, the section name
|
|
must be prepended to the variable name, separated by a slash (/).
|
|
sectionelse is executed when there are no values in the loop
|
|
variable.
|
|
</para>
|
|
<example>
|
|
<title>section</title>
|
|
<programlisting>
|
|
|
|
|
|
{* this example will print out all the values of the $custid array *}
|
|
{section name=customer loop=$custid}
|
|
id: {$customer/custid}<br>
|
|
{/section}
|
|
|
|
OUTPUT:
|
|
|
|
id: 1000<br>
|
|
id: 1001<br>
|
|
id: 1002<br>
|
|
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>section loop variable</title>
|
|
<programlisting>
|
|
|
|
{* the loop variable only determines the number of times to loop.
|
|
you can access any variable from the template within the section.
|
|
This example assumes that $custid, $name and $address are all
|
|
arrays containing the same number of values *}
|
|
{section name=customer loop=$custid}
|
|
id: {$customer/custid}<br>
|
|
name: {$customer/name}<br>
|
|
address: {$customer/address}<br>
|
|
<p>
|
|
{/section}
|
|
|
|
|
|
OUTPUT:
|
|
|
|
id: 1000<br>
|
|
name: John Smith<br>
|
|
address: 253 N 45th
|
|
<p>
|
|
id: 1001<br>
|
|
name: Jack Jones<br>
|
|
address: 417 Mulberry ln
|
|
<p>
|
|
id: 1002<br>
|
|
name: Jane Munson
|
|
address: 5605 apple st
|
|
<p>
|
|
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>section names</title>
|
|
<programlisting>
|
|
|
|
{* the name of the section can be anything you like,
|
|
and it is used to reference the data within the section *}
|
|
{section name=mydata loop=$custid}
|
|
id: {$mydata/custid}<br>
|
|
name: {$mydata/name}<br>
|
|
address: {$mydata/address}<br>
|
|
<p>
|
|
{/section}
|
|
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>nested sections</title>
|
|
<programlisting>
|
|
|
|
{* sections can be nested as deep as you like. With nested sections,
|
|
you can access complex data structures, such as multi-dimensional
|
|
arrays. In this example, $customer/contact_type is an array of
|
|
contact types for the current customer. *}
|
|
{section name=customer loop=$custid}
|
|
id: {$customer/custid}<br>
|
|
name: {$customer/name}<br>
|
|
address: {$customer/address}<br>
|
|
{section name=contact loop=$customer/contact_type}
|
|
{$customer/contact/contact_type}: {$customer/contact/contact_info}<br>
|
|
{/section}
|
|
<p>
|
|
{/section}
|
|
|
|
|
|
OUTPUT:
|
|
|
|
id: 1000<br>
|
|
name: John Smith<br>
|
|
address: 253 N 45th
|
|
home phone: 555-555-5555
|
|
cell phone: 555-555-5555
|
|
e-mail: john@mydomain.com
|
|
<p>
|
|
id: 1001<br>
|
|
name: Jack Jones<br>
|
|
address: 417 Mulberry ln
|
|
home phone: 555-555-5555
|
|
cell phone: 555-555-5555
|
|
e-mail: jack@mydomain.com
|
|
<p>
|
|
id: 1002<br>
|
|
name: Jane Munson
|
|
address: 5605 apple st
|
|
home phone: 555-555-5555
|
|
cell phone: 555-555-5555
|
|
e-mail: jane@mydomain.com
|
|
<p>
|
|
|
|
|
|
</programlisting>
|
|
</example>
|
|
|
|
<example>
|
|
<title>sections and associative arrays</title>
|
|
<programlisting>
|
|
|
|
{* This is an example of printing an associative array
|
|
of data within a section *}
|
|
{section name=customer loop=$contacts}
|
|
{$customer/contacts.name}<br>
|
|
{$customer/contacts.home}<br>
|
|
{$customer/contacts.cell}<br>
|
|
{$customer/contacts.email}<br>
|
|
{/section}
|
|
|
|
|
|
OUTPUT:
|
|
|
|
name: John Smith<br>
|
|
home: 555-555-5555<p>
|
|
cell: 555-555-5555<p>
|
|
e-mail: john@mydomain.com<p>
|
|
name: Jack Jones<br>
|
|
home phone: 555-555-5555<p>
|
|
cell phone: 555-555-5555<p>
|
|
e-mail: jack@mydomain.com<p>
|
|
name: Jane Munson<p>
|
|
home phone: 555-555-5555<p>
|
|
cell phone: 555-555-5555<p>
|
|
e-mail: jane@mydomain.com<p>
|
|
|
|
|
|
</programlisting>
|
|
</example>
|
|
|
|
|
|
|
|
<example>
|
|
<title>sectionelse</title>
|
|
<programlisting>
|
|
|
|
{* sectionelse will execute in the case there are no $custid values *}
|
|
{section name=customer loop=$custid}
|
|
id: {$customer/custid}<br>
|
|
{sectionelse}
|
|
there are no values in $custid.
|
|
{/section}
|
|
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
Sections also have their own variables that handle section properties.
|
|
These are indicated by percent signs around the variable name, like so:
|
|
%sectionname.varname%
|
|
</para>
|
|
<sect3>
|
|
<title>index</title>
|
|
<para>
|
|
index is used to display the current loop iteration,
|
|
starting with zero.
|
|
</para>
|
|
<example>
|
|
<title>section property index</title>
|
|
<programlisting>
|
|
{section name=customer loop=$custid}
|
|
{%customer.index%} id: {$customer/custid}<br>
|
|
{/section}
|
|
|
|
|
|
OUTPUT:
|
|
|
|
0 id: 1000<br>
|
|
1 id: 1001<br>
|
|
2 id: 1002<br>
|
|
|
|
</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3>
|
|
<title>rownum</title>
|
|
<para>
|
|
rownum is used to display the current loop iteration,
|
|
starting with one.
|
|
</para>
|
|
<example>
|
|
<title>section property rownum</title>
|
|
<programlisting>
|
|
{section name=customer loop=$custid}
|
|
{%customer.rownum%} id: {$customer/custid}<br>
|
|
{/section}
|
|
|
|
|
|
OUTPUT:
|
|
|
|
1 id: 1000<br>
|
|
2 id: 1001<br>
|
|
3 id: 1002<br>
|
|
|
|
</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3>
|
|
<title>loop</title>
|
|
<para>
|
|
loop is used to display the total number
|
|
of iterations this section is looped. This can be used
|
|
inside or after the section.
|
|
</para>
|
|
<example>
|
|
<title>section property index</title>
|
|
<programlisting>
|
|
{section name=customer loop=$custid}
|
|
{%customer.index%} id: {$customer/custid}<br>
|
|
{/section}
|
|
|
|
There were {%customer.loop%} customers shown above.
|
|
|
|
OUTPUT:
|
|
|
|
0 id: 1000<br>
|
|
1 id: 1001<br>
|
|
2 id: 1002<br>
|
|
|
|
There were 3 customers shown above.
|
|
|
|
</programlisting>
|
|
</example>
|
|
</sect3>
|
|
<sect3>
|
|
<title>show</title>
|
|
<para>
|
|
show is used both as a parameter to section,
|
|
as well as displaying its value. show is a
|
|
boolean value, true or false. If false, the
|
|
section will not be displayed. If there is a
|
|
sectionelse present, that will be alternately
|
|
displayed.
|
|
</para>
|
|
<example>
|
|
<title>section property rownum</title>
|
|
<programlisting>
|
|
{* $show_customer_info may have been passed from the PHP
|
|
application, to regulate whether or not this section shows *}
|
|
{section name=customer loop=$custid show=$show_customer_info}
|
|
{%customer.rownum%} id: {$customer/custid}<br>
|
|
{/section}
|
|
|
|
{if %customer.show%}
|
|
the section was shown.
|
|
{else}
|
|
the section was not shown.
|
|
{/if}
|
|
|
|
|
|
OUTPUT:
|
|
|
|
1 id: 1000<br>
|
|
2 id: 1001<br>
|
|
3 id: 1002<br>
|
|
|
|
the section was shown.
|
|
|
|
</programlisting>
|
|
</example>
|
|
</sect3>
|
|
</sect2>
|
|
<sect2>
|
|
<title>strip</title>
|
|
<para>
|
|
Many times web designers
|
|
run into the issue where white space and carriage returns
|
|
affect the output of the rendered HTML (browser "features"), so you
|
|
must run all your tags together in the template to get the
|
|
desired results. This usually ends up in unreadable or
|
|
unmanagable templates.
|
|
</para>
|
|
<para>
|
|
Anything within {strip}{/strip} tags in Smarty are stripped of
|
|
the extra spaces or carriage returns at the beginnings and
|
|
ends of the lines before they are displayed.
|
|
This way you can keep your templates readable, and not worry
|
|
about extra white space causing problems.
|
|
</para>
|
|
<example>
|
|
<title>strip tags</title>
|
|
<programlisting>
|
|
|
|
{* the following will be all run into one line upon output *}
|
|
{strip}
|
|
<table border=0>
|
|
<tr>
|
|
<td>
|
|
<A HREF="{$url}">
|
|
<font color="red">This is a test</font>
|
|
</A>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
{/strip}
|
|
|
|
|
|
OUTPUT:
|
|
|
|
<table border=0><tr><td><A HREF="http://my.domain.com"><font color="red">This is a test</font></A></td></tr></table>
|
|
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
Notice that in the above example, all the lines begin and end
|
|
with HTML tags. Be aware that all the lines are run together.
|
|
If you have plain text at the beginning or end of any line,
|
|
they will be run together, and may not be desired results.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="custom.functions">
|
|
<title>Custom Functions</title>
|
|
<para>
|
|
Custom functions in Smarty work much the same as the built-in functions
|
|
syntactically. Two custom functions come bundled with Smarty. You can
|
|
also write your own.
|
|
</para>
|
|
<sect2>
|
|
<title>html_options</title>
|
|
<para>
|
|
html_options is a custom function that creates html option
|
|
lists with provided data. It takes care of which item is
|
|
selected by default as well.
|
|
</para>
|
|
<example>
|
|
<title>html_options</title>
|
|
<programlisting>
|
|
|
|
{* assume that $cust_ids, and $cust_names are arrays of values,
|
|
and $customer_id may or may not be set to a value *}
|
|
|
|
<select name=customer_id>
|
|
{html_options values=$cust_ids selected=$customer_id output=$cust_names}
|
|
</select>
|
|
|
|
|
|
OUTPUT:
|
|
|
|
<select name=customer_id>
|
|
<option value="1000">Joe Schmoe<option>
|
|
<option value="1001" selected>Jack Smith<option>
|
|
<option value="1002">Jane Johnson<option>
|
|
<option value="1003">Charlie Brown<option>
|
|
</select>
|
|
|
|
</programlisting>
|
|
</example>
|
|
</sect2>
|
|
<sect2>
|
|
<title>html_select_date</title>
|
|
<para>
|
|
html_select_date is a custom function that creates date dropdowns
|
|
for you. It can display any or all of year, month, and day. Possible
|
|
attributes are (attr name, type, default val):
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>prefix,string,"Date_"</para></listitem>
|
|
<listitem><para>time,timestamp,(current time)</para></listitem>
|
|
<listitem><para>start_year,int,(current year)</para></listitem>
|
|
<listitem><para>end_year int (same as start_year)</para></listitem>
|
|
<listitem><para>display_days, boolean, true</para></listitem>
|
|
<listitem><para>display_months, boolean, true</para></listitem>
|
|
<listitem><para>display_years, boolean, true</para></listitem>
|
|
<listitem><para>month_format, strftime, "%B"</para></listitem>
|
|
<listitem><para>day_format, strftime, "%02d"</para></listitem>
|
|
<listitem><para>year_as_text, boolean, true</para></listitem>
|
|
</itemizedlist>
|
|
<example>
|
|
<title>html_select_date</title>
|
|
<programlisting>
|
|
|
|
{html_select_date}
|
|
|
|
|
|
OUTPUT:
|
|
|
|
<select name="Date_Month">
|
|
<option value="1">January</option>
|
|
<option value="2">February</option>
|
|
<option value="3">March</option>
|
|
<option value="4">April</option>
|
|
<option value="5">May</option>
|
|
<option value="6">June</option>
|
|
<option value="7">July</option>
|
|
<option value="8">August</option>
|
|
<option value="9">September</option>
|
|
<option value="10">October</option>
|
|
<option value="11">November</option>
|
|
<option value="12" selected>December</option>
|
|
</select>
|
|
<select name="Date_Day">
|
|
<option value="1">01</option>
|
|
<option value="2">02</option>
|
|
<option value="3">03</option>
|
|
<option value="4">04</option>
|
|
<option value="5">05</option>
|
|
<option value="6">06</option>
|
|
<option value="7">07</option>
|
|
<option value="8">08</option>
|
|
<option value="9">09</option>
|
|
<option value="10">10</option>
|
|
<option value="11">11</option>
|
|
<option value="12">12</option>
|
|
<option value="13" selected>13</option>
|
|
<option value="14">14</option>
|
|
<option value="15">15</option>
|
|
<option value="16">16</option>
|
|
<option value="17">17</option>
|
|
<option value="18">18</option>
|
|
<option value="19">19</option>
|
|
<option value="20">20</option>
|
|
<option value="21">21</option>
|
|
<option value="22">22</option>
|
|
<option value="23">23</option>
|
|
<option value="24">24</option>
|
|
<option value="25">25</option>
|
|
<option value="26">26</option>
|
|
<option value="27">27</option>
|
|
<option value="28">28</option>
|
|
<option value="29">29</option>
|
|
<option value="30">30</option>
|
|
<option value="31">31</option>
|
|
</select>
|
|
<select name="Date_Year">
|
|
<option value="2001" selected>2001</option>
|
|
</select>
|
|
|
|
</programlisting>
|
|
</example>
|
|
|
|
|
|
<example>
|
|
<title>html_select_date</title>
|
|
<programlisting>
|
|
|
|
|
|
{html_select_date prefix="StartDate" time=$time start_year=1995 end_year=2001 display_days=false}
|
|
|
|
OUTPUT:
|
|
|
|
<select name="StartDateMonth">
|
|
<option value="1">January</option>
|
|
<option value="2">February</option>
|
|
<option value="3">March</option>
|
|
<option value="4">April</option>
|
|
<option value="5">May</option>
|
|
<option value="6">June</option>
|
|
<option value="7">July</option>
|
|
<option value="8">August</option>
|
|
<option value="9">September</option>
|
|
<option value="10">October</option>
|
|
<option value="11">November</option>
|
|
<option value="12" selected>December</option>
|
|
</select>
|
|
<select name="StartDateYear">
|
|
<option value="1999">1995</option>
|
|
<option value="1999">1996</option>
|
|
<option value="1999">1997</option>
|
|
<option value="1999">1998</option>
|
|
<option value="1999">1999</option>
|
|
<option value="2000" selected>2000</option>
|
|
<option value="2001">2001</option>
|
|
</select>
|
|
|
|
</programlisting>
|
|
</example>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Creating your own Custom Functions</title>
|
|
<para>
|
|
Creating your own functions is a fairly straight forward process.
|
|
The best way is to look at the ones that come with Smarty as
|
|
examples. The function names begin with smarty_func_ and they are
|
|
located in the Smarty.addons.php file.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>add your function to the Smarty.addons.php file.
|
|
It is recommended that you prepend your function name
|
|
with smarty_func_</para></listitem>
|
|
<listitem><para>map a template function name to your PHP function.
|
|
This is done at the top of the Smarty.class.php file
|
|
in the $custom_funcs array.</para></listitem>
|
|
<listitem><para>Thats it! you can now call that function
|
|
from within Smarty.</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
All attributes passed to custom functions are passed into the
|
|
first argument as an associative array. One way to get to those
|
|
values is to call extract(func_get_arg(0)); at the top of your
|
|
function. Anything that the function returns gets displayed
|
|
in place of the tag in the template.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
<sect1 id="variable.modifiers">
|
|
<title>Variable Modifiers</title>
|
|
<para>
|
|
Variable modifiers are a bit different than
|
|
<link linkend="custom.functions">custom functions</link>.
|
|
They do just what they sound like, they modify variables before
|
|
they are displayed to the template. The best way to explain
|
|
these are by example.
|
|
</para>
|
|
<example>
|
|
<title>variable modifiers</title>
|
|
<programlisting>
|
|
|
|
{* this displays a variable, unmodified *}
|
|
{$articleTitle}
|
|
|
|
OUTPUT:
|
|
|
|
Burger King fire leaves seven pregnant teenagers <jobless>
|
|
|
|
|
|
{* this displays the variable in all upper case *}
|
|
{$articleTitle|upper}
|
|
|
|
OUTPUT:
|
|
|
|
BURGER KING FIRE LEAVES SEVEN PREGNANT TEENAGERS <JOBLESS>
|
|
|
|
|
|
{* this displays the variable html escaped *}
|
|
{$articleTitle|escape}
|
|
|
|
OUTPUT:
|
|
|
|
Burger King fire leaves seven pregnant teenagers &lt;jobless&gt;
|
|
|
|
|
|
{* this displays the variable uppercased AND html escaped *}
|
|
{$articleTitle|upper|escape}
|
|
|
|
OUTPUT:
|
|
|
|
BURGER KING FIRE LEAVES SEVEN PREGNANT TEENAGERS &lt;JOBLESS&gt;
|
|
|
|
|
|
{* an example of passing a parameter to a modifier:
|
|
this displays the variable url escaped *}
|
|
{$articleTitle|escape:"url"}
|
|
|
|
OUTPUT:
|
|
|
|
Burger+King+fire+leaves+seven+pregnant+teenagers+%3Cjobless%3e
|
|
|
|
|
|
{* print the first 24 characters of this variable, and
|
|
follow with ... if it was longer *}
|
|
{$articleTitle|truncate:24:"..."}
|
|
|
|
OUTPUT:
|
|
|
|
Burger King fire...
|
|
|
|
|
|
{* print the date in default format *}
|
|
{$startTime|date_format}
|
|
|
|
OUTPUT:
|
|
|
|
Dec 13, 2000
|
|
|
|
|
|
{* print the hour, minute and second portion of a date *}
|
|
{$startTime|date_format:"%h:%m:%s"}
|
|
|
|
OUTPUT:
|
|
|
|
10:33:02
|
|
|
|
{* print a number to the first two decimals *}
|
|
{$amount|string_format:"%.2f"}
|
|
|
|
OUTPUT:
|
|
|
|
24.02
|
|
|
|
{* print "Home Page" if $title is empty *}
|
|
{$title|default:"Home Page"}
|
|
|
|
OUTPUT:
|
|
|
|
Home Page
|
|
|
|
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
All modifiers will get the value of the variable as the first argument,
|
|
and must return a single value. Modifier parameters are separated by colons.
|
|
Any additional parameters passed to a modifier are passed as-is positionally,
|
|
much like calling a PHP function. You can also use native
|
|
PHP functions as modifiers, but only if they expect the correct
|
|
arguments. If they do not, you can always write a wrapper function
|
|
in Smarty to get what you want (date_format is a wrapper function
|
|
to strftime() for example.) You can chain as many modifiers
|
|
together on a variable as you like, separating each with a vertical
|
|
pipe "|".
|
|
</para>
|
|
<para>
|
|
NOTE: if you apply a modifier to an array
|
|
instead of a single value variable, the modifier will be applied to every
|
|
value in that array. If you really want the entire array passed
|
|
to the modifier, you must prepend it with an "@" sign like so:
|
|
{$articleTitle|@count} (this will print out the number of elements
|
|
in the $articleTitle array.)
|
|
</para>
|
|
<sect2>
|
|
<title>capitalize</title>
|
|
<para>
|
|
This is used to capitalize the first letter of all words in a variable.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="date.format">
|
|
<title>date_format</title>
|
|
<para>
|
|
This formats a date into the given strftime() format. All dates
|
|
should be passed to Smarty as a timestamp so that the template
|
|
designer has full control of how this date is formatted. The
|
|
default format is "%b %e, %Y", or "Jan 4, 2001" for example.
|
|
These are the possible conversion specifiers:
|
|
</para>
|
|
<example>
|
|
<title>date_format conversion specifiers</title>
|
|
<programlisting>
|
|
%a - abbreviated weekday name according to the current locale
|
|
|
|
%A - full weekday name according to the current locale
|
|
|
|
%b - abbreviated month name according to the current locale
|
|
|
|
%B - full month name according to the current locale
|
|
|
|
%c - preferred date and time representation for the current locale
|
|
|
|
%C - century number (the year divided by 100 and truncated to an integer, range 00 to 99)
|
|
|
|
%d - day of the month as a decimal number (range 00 to 31)
|
|
|
|
%D - same as %m/%d/%y
|
|
|
|
%e - day of the month as a decimal number, a single digit is preceded by a space (range ' 1' to '31')
|
|
|
|
%h - same as %b
|
|
|
|
%H - hour as a decimal number using a 24-hour clock (range 00 to 23)
|
|
|
|
%I - hour as a decimal number using a 12-hour clock (range 01 to 12)
|
|
|
|
%j - day of the year as a decimal number (range 001 to 366)
|
|
|
|
%m - month as a decimal number (range 01 to 12)
|
|
|
|
%M - minute as a decimal number
|
|
|
|
%n - newline character
|
|
|
|
%p - either `am' or `pm' according to the given time value, or the corresponding strings for the current locale
|
|
|
|
%r - time in a.m. and p.m. notation
|
|
|
|
%R - time in 24 hour notation
|
|
|
|
%S - second as a decimal number
|
|
|
|
%t - tab character
|
|
|
|
%T - current time, equal to %H:%M:%S
|
|
|
|
%u - weekday as a decimal number [1,7], with 1 representing Monday
|
|
|
|
%U - week number of the current year as a decimal number, starting with the first Sunday as the first day of the first week
|
|
|
|
%V - The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1
|
|
is the first week that has at least 4 days in the current year, and with Monday as the first day of the week.
|
|
|
|
%W - week number of the current year as a decimal number, starting with the first Monday as the first day of the first week
|
|
|
|
%w - day of the week as a decimal, Sunday being 0
|
|
|
|
%x - preferred date representation for the current locale without the time
|
|
|
|
%X - preferred time representation for the current locale without the date
|
|
|
|
%y - year as a decimal number without a century (range 00 to 99)
|
|
|
|
%Y - year as a decimal number including the century
|
|
|
|
%Z - time zone or name or abbreviation
|
|
|
|
%% - a literal `%' character
|
|
</programlisting>
|
|
</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>
|
|
This is used to html or url escape a variable. By default,
|
|
the variable is html escaped. possible arguments are "url" or "html".
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>lower</title>
|
|
<para>
|
|
This is used to lowercase a variable.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>replace</title>
|
|
<para>
|
|
A simple search and replace on a variable. The first argument is
|
|
what to search for, the second argument is what to replace it with.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>spacify</title>
|
|
<para>
|
|
spacify is a way to insert spaces between every character of a variable.
|
|
You can optionally pass a different character (or string) to insert.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>string_format</title>
|
|
<para>
|
|
This is a way to format strings, such as decimal numbers and such.
|
|
Use the syntax for sprintf for the formatting.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>strip_tags</title>
|
|
<para>
|
|
This strips out markup tags, basically anything between < and >.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>truncate</title>
|
|
<para>
|
|
This truncates a variable to a character length, default is 80. As
|
|
an optional second parameter, you can specify a string of text
|
|
to display at the end if the variable was truncated. The
|
|
characters in the string are included with the original truncation length.
|
|
By default, truncate will attempt to cut off at a word boundary. If
|
|
you want to cut off at the exact character length, pass the optional
|
|
third parameter of true.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>upper</title>
|
|
<para>
|
|
This is used to uppercase a variable.
|
|
</para>
|
|
</sect2>
|
|
<sect2>
|
|
<title>Creating your own Variable Modifiers</title>
|
|
<para>
|
|
Creating your own modifiers is a fairly straight forward process.
|
|
The best way is to look at the ones that come with Smarty as
|
|
examples. The function names begin with smarty_mod_ and they are
|
|
located in the Smarty.addons.php file.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>add your modifier to the Smarty.addons.php file.
|
|
It is recommended that you prepend your function name
|
|
with smarty_mod_</para></listitem>
|
|
<listitem><para>map a template modifier name to your PHP function.
|
|
This is done at the top of the Smarty.class.php file
|
|
in the $custom_mods array.</para></listitem>
|
|
<listitem><para>Thats it! you can now use that modifier
|
|
from within Smarty.</para></listitem>
|
|
</itemizedlist>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
<chapter>
|
|
<title>Troubleshooting</title>
|
|
<para></para>
|
|
<sect1>
|
|
<title>Smarty/PHP errors</title>
|
|
<para>
|
|
Smarty can catch many errors such as missing tag attributes
|
|
or malformed variable names. If this happens, you will see an error
|
|
similar to the following:
|
|
</para>
|
|
|
|
<example>
|
|
<title>Smarty errors</title>
|
|
<programlisting>
|
|
|
|
Warning: Smarty: [in index.tpl line 4]: syntax error: unknown tag - '%blah'
|
|
in /path/to/smarty/Smarty.class.php on line 1041
|
|
|
|
Fatal error: Smarty: [in index.tpl line 28]: syntax error: missing section name
|
|
in /path/to/smarty/Smarty.class.php on line 1041
|
|
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
Smarty shows you the template name, the line number and the error.
|
|
Everything beyond that is PHP error messages which you can ignore.
|
|
</para>
|
|
|
|
<para>
|
|
There are certain errors that Smarty cannot catch, such as missing
|
|
close tags. These types of errors can end up in PHP compile-time
|
|
errors.
|
|
</para>
|
|
|
|
<example>
|
|
<title>PHP errors</title>
|
|
<programlisting>
|
|
|
|
Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75
|
|
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
When you encounter a PHP error when attempting to display the
|
|
template in a browser, the error line number will correspond to the
|
|
compiled PHP script, not the template itself. This may be a bit
|
|
confusing. Usually you can look at the template and spot the syntax
|
|
error. Here are some common things to look for: missing close tags for
|
|
{if}{/if} or {section}{/section}, or syntax of logic within an {if}
|
|
tag. If you can't find the error, you must open the compiled PHP file
|
|
and go to the line number to figure out where the corresponding error
|
|
is in the template.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
<chapter id="tips">
|
|
<title>Tips & Tricks</title>
|
|
<para>
|
|
</para>
|
|
<sect1>
|
|
<title>Dates</title>
|
|
<para>
|
|
As a rule of thumb, always pass dates to Smarty as timestamps.
|
|
This allows template designers to use <link
|
|
linkend="date.format">date_format</link> for full control over date
|
|
formatting, and also makes it easy to compare dates if necessary.
|
|
</para>
|
|
<example>
|
|
<title>using date_format</title>
|
|
<programlisting>
|
|
|
|
{$startDate|date_format}
|
|
|
|
OUTPUT:
|
|
|
|
Jan 4, 2001
|
|
|
|
|
|
{$startDate|date_format:"%Y/%m/%d"}
|
|
|
|
OUTPUT:
|
|
|
|
2001/01/04
|
|
|
|
|
|
{if $date1 < $date2}
|
|
...
|
|
{/if}
|
|
|
|
</programlisting>
|
|
</example>
|
|
<para>
|
|
{html_select_date}, an included custom function with Smarty, also
|
|
expects a timestamp as the default value. When using {html_select_date}
|
|
in a template, The programmer will most likely want to convert the
|
|
output from the form back into timestamp format. Here is a function to
|
|
help you with that.
|
|
</para>
|
|
<example>
|
|
<title>converting form date elements back to a timestamp</title>
|
|
<programlisting>
|
|
|
|
// this assumes your form elements are named
|
|
// startDate_Day, startDate_Month, startDate_Year
|
|
|
|
$startDate = makeTimestamp($startDate_Year,$startDate_Month,$startDate_day);
|
|
|
|
function makeTimeStamp($year="",$month="",$day="")
|
|
{
|
|
if(empty($year))
|
|
$year = strftime("%Y");
|
|
if(empty($month))
|
|
$month = strftime("%m");
|
|
if(empty($day))
|
|
$day = strftime("%d");
|
|
|
|
return mktime(0,0,0,$month,$day,$year);
|
|
}
|
|
|
|
</programlisting>
|
|
</example>
|
|
</sect1>
|
|
</chapter>
|
|
<chapter id="bugs">
|
|
<title>BUGS</title>
|
|
<para>
|
|
Check the BUGS file that comes with the latest distribution of Smarty, or
|
|
check the website.
|
|
</para>
|
|
</chapter>
|
|
<chapter id="pear">
|
|
<title>PEAR</title>
|
|
<para>
|
|
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. un*x users check
|
|
/usr/local/lib/php. Windows users check C:/php/pear.
|
|
</para>
|
|
</chapter>
|
|
<chapter id="credits">
|
|
<title>CREDITS</title>
|
|
<para>
|
|
Monte Ohrt <monte@ispi.net>: Idea of compiling into PHP scripts,
|
|
initial implementation, documentation.
|
|
</para>
|
|
<para>
|
|
Andrei Zmievski <andrei@ispi.net>: Rewrote parser from scratch, added
|
|
custom modifier functionality, and much more.
|
|
</para>
|
|
<para>
|
|
Anne Holz <anne@ispi.net>: Contributed several ideas for formatting features.
|
|
</para>
|
|
<para>
|
|
Frank Kromann <fmk@php.net>: Idea of custom function ability.
|
|
</para>
|
|
<para>
|
|
A special thanks goes to all the people that have contributed other
|
|
templating solutions to the PHP community which we learned a lot from.
|
|
</para>
|
|
<para>
|
|
A special thanks goes to all the members of the php-template mailing list,
|
|
who shared and brought many ideas to the table.
|
|
</para>
|
|
<para>
|
|
Rasmus Lerdorf <rasmus@php.net>: For starting what eventually became
|
|
the coolest programming language ever.
|
|
</para>
|
|
</chapter>
|
|
</book>
|