smarty/docs.sgml

<!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.3</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
			{}, {{}}, &lt;!--{}--&gt;, 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>
		<listitem><para>Built-in caching support (new in 1.3.0)</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 id="section.caching">
        <title>Caching</title>
		<para>
            Smarty can cache the output of your generated templates. By default
            this is disabled. If you <link linkend="setting.caching">enable
            caching</link>, Smarty will store a copy of the generated template
            output, and use this until the copy <link
            linkend="setting.cache.lifetime">expires</link>, regenerating a new
            one. The default cache expire time is one hour, and can be
            configured from the class. The exception to the rule is the <link
            linkend="function.insert">insert</link> tag. Anything generated by
            the insert tag is not cached, but run dynamically on every
            invocation, even within cached content.
		</para>
        <para>
            TECHNICAL NOTE: Any time you change a template, change values in
            config files or change the content that gets displayed in a
            template, you must either clear the caches that are affected, or
            wait for the cache to expire to see the results of the changes. You
            can either do this manually by deleting files from the cache
            directory, or programatically with <link
            linkend="api.clear.cache">clear_cache</link> or <link
            linkend="api.clear.all.cache">clear_all_cache</link>.
        </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. Smarty creates PHP scripts from the templates.
        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. If you plan on using caching,
        you will need to create a "cache" directory, also with permission to
        write files.
		</para>
        <para>
        TECHNICAL NOTE: You can get around the need to allow the web server
        user write access to compile templates. Smarty needs to compile the
        templates only once. This can be done from the command line, using the
        CGI version of PHP. example: "php -q index.php". Once the templates are
        compiled, they should run fine from the web environment. If you change
        a template, you must recompile from the command line again. If you do
        not have the CGI version of PHP available and you are concerned about
        world-writable directory access, you can chmod 777 the compile_dir, let
        the templates compile once as the web server user, then change the
        directory mode back to 700. If you are using the caching feature of
        Smarty, the cache directory must always have write access for the web
        server user.
        </para>
        <para>
        TECHNICAL NOTE: If you do not have access to the php.ini file, you can
        change non-server settings (such as your include_path) with the
        ini_set() command (available in PHP 4.0.4 or later.) example:
        ini_set("include_path",".:/usr/local/lib/php");
        </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-[version].tar.gz
mkdir templates_c
chown nobody:nobody templates_c
chmod 700 templates_c
# if you are using caching, do the following
mkdir cache
chown nobody:nobody cache
chmod 700 cache
</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. The default settings work for all of the examples and tutorials.
		</para>
	<sect1>
		<title>Configuration variables</title>
		<para></para>
		<sect2 id="setting.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>
			<para>
                TECHNICAL NOTE: It is not mandatory to put this directory under
                the web server document root.
			</para>
		</sect2>		
		<sect2 id="setting.compile.dir">
			<title>$compile_dir</title>
			<para>
				This is the name of the directory where compiled templates are
				located. By default this is "./templates_c". This was
				added to Smarty version 1.2.1.
			</para>
			<para>
                TECHNICAL NOTE: This setting must be either a relative or
                absolute path. include_path is not used for writing files.
            </para>
            <para>    
                TECHNICAL NOTE: It is not mandatory to put this directory under
                the web server document root.
			</para>
		</sect2>
		<sect2 id="setting.config.dir">
			<title>$config_dir</title>
			<para>
				This is the directory used to store config files used in the templates.
				Default is "./configs".
			</para>
			<para>
                TECHNICAL NOTE: It is not mandatory to put this directory under
                the web server document root.
			</para>
		</sect2>
		<sect2 id="setting.global.assign">
			<title>$global_assign</title>
			<para>
                This is a list of variables that are always implicitly assigned
                to the template engine. This is handy for making global
                variables or server variables available to all templates
                without having to manually assign them. $SCRIPT_NAME is
                globally assigned by default.
			</para>
		</sect2>
		<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 templates 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. Once an application is put into production and
				it is initially compiled, the compile_check step is no longer
				needed. Be sure to set $compile_check to "false" to improve
				performance! 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. See <link
				linkend="setting.force.compile">$force_compile</link>
			</para>
		</sect2>
		<sect2 id="setting.force.compile">
			<title>$force_compile</title>
			<para>
				This forces Smarty to compile all templates on every
				invocation. This setting overrides $compile_check. By default
				this is disabled. This is handy for development and debugging.
				It should never be used in a production environment.
			</para>
		</sect2>
		<sect2 id="setting.caching">
			<title>$caching</title>
			<para>
                This tells Smarty whether or not to cache the output of the
                templates. By default this is set to false. If your templates
                generate the same content over and over, it is advisable to
                turn on caching. This will result significant performance
                gains. You can also have multiple caches for the same template.
                See <link linkend="api.is.cached">is_cached</link> for details.
                This was added to Smarty 1.3.0.
			</para>
		</sect2>
		<sect2 id="setting.cache.dir">
			<title>$cache_dir</title>
			<para>
				This is the name of the directory where template caches are
				located. By default this is "./cache". This was
				added to Smarty version 1.3.0.
			</para>
			<para>
                TECHNICAL NOTE: This setting must be either a relative or
                absolute path. include_path is not used for writing files.
            </para>
			<para>
                TECHNICAL NOTE: It is not mandatory to put this directory under
                the web server document root.
			</para>
		</sect2>
		<sect2 id="setting.cache.lifetime">
			<title>$cache_lifetime</title>
			<para>
				This is the length of time in seconds that a template cache is
				valid. Once this time has expired, the cache will be
				regenerated. $caching must be set to "true" for this setting to
				work. You can also force the cache to expire with <link
				linkend="api.clear.all.cache">clear_all_cache</link>. This was
				added to Smarty 1.3.0.
			</para>
		</sect2>
		<sect2 id="setting.tpl.file.ext">
			<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 id="setting.allow.php">
			<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 id="setting.php.handling">
			<title>$php_handling</title>
			<para>
                This tells Smarty how to handle PHP code embedded in the
                tempalates. There are four possible settings, default being
                SMARTY_PHP_PASSTHRU.
            </para>    
		    <itemizedlist>
		    <listitem><para>SMARTY_PHP_PASSTHRU - Smarty echos tags as-is.</para></listitem>
		    <listitem><para>SMARTY_PHP_QUOTE - Smarty quotes the tags as
                html entities.</para></listitem>
		    <listitem><para>SMARTY_PHP_REMOVE - Smarty removes the tags from
                the templates.</para></listitem>
		    <listitem><para>SMARTY_PHP_ALLOW - Smarty will execute the tags
                as PHP code.</para></listitem>
            </itemizedlist>
            <para>
                NOTE: Embedding PHP code into templates is highly discouraged.
                Use <link linkend="custom.functions">custom functions</link> or
                <link linkend="variable.modifiers">modifiers</link> instead.
			</para>
		</sect2>
		<sect2 id="setting.left.delimiter">
			<title>$left_delimiter</title>
			<para>
				This is the left delimiter used by the template language. Default is "{".
			</para>
		</sect2>
		<sect2 id="setting.right.delimiter">
			<title>$right_delimiter</title>
			<para>
				This is the right delimiter used by the template language. Default is "}".			
			</para>
		</sect2>
		<sect2 id="setting.custom.funcs">
			<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. The default custom
                functions that come bundled with Smarty are located in
                Smarty.addons.php.
			</para>
		</sect2>
		<sect2 id="setting.custom.mods">
			<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. The default variable modifiers
                that come bundled with Smarty are located in
                Smarty.addons.php.
			</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 id="api.assign">
			<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. You can
                explicitly pass name/value pairs, or associative arrays
                containing the name/value pairs.
			</para>
<example>
<title>assign</title>
<programlisting>

// passing name/value pairs
$smarty->assign("Name","Fred");
$smarty->assign("Address",$address);

// passing an associative array
$smarty->assign(array("city" => "Lincoln","state" => "Nebraska"));

</programlisting>
</example>
		</sect2>
		<sect2 id="api.append">
			<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 variables in the template. You
                can explicitly pass name/value pairs, or associative arrays
                containing the name/value pairs.
			</para>
<example>
<title>append</title>
<programlisting>

// passing name/value pairs
$smarty->append("Name","Fred");
$smarty->append("Address",$address);

// passing an associative array
$smarty->append(array("city" => "Lincoln","state" => "Nebraska"));

</programlisting>
</example>
		</sect2>
		<sect2 id="api.clear.assign">
			<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. This
                can be a single value, or an array of values. Array
                functionality was added to Smarty 1.3.0.
			</para>
<example>
<title>clear_assign</title>
<programlisting>

// clear a single variable
$smarty->clear_assign("Name");

// clear multiple variables
$smarty->clear_assign(array("Name","Address","Zip"));


</programlisting>
</example>
		</sect2>
		<sect2 id="api.clear.all.assign">
			<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>
<example>
<title>clear_all_assign</title>
<programlisting>

// clear all assigned variables
$smarty->clear_all_assign();

</programlisting>
</example>
		</sect2>
		<sect2 id="api.register.function">
			<title>register_function</title>
			<funcsynopsis>
			<funcprototype>
			<funcdef>void <function>register_function</function></funcdef>
				<paramdef>string <parameter>funcname</parameter></paramdef>
				<paramdef>string <parameter>funcimpl</parameter></paramdef>
			</funcprototype>
			</funcsynopsis>
			<para>
                Use this to dynamically register functions with Smarty. Pass in
                the Smarty function name, followed by the actual function name
                that it is mapped to.
			</para>
<example>
<title>register_function</title>
<programlisting>

$smarty->register_function("date_now","print_current_date");

function print_current_date ($params) {
    extract($params);
    if(empty($format))
        $format="%b %e, %Y";
    echo strftime($format,time());
}

// now you can use this in Smarty to print the current date: {date_now}
// or, {date_now format="%Y/%m/%d"} to format it.

</programlisting>
</example>
		</sect2>
		<sect2 id="api.register.modifier">
			<title>register_modifier</title>
			<funcsynopsis>
			<funcprototype>
			<funcdef>void <function>register_modifier</function></funcdef>
				<paramdef>string <parameter>modname</parameter></paramdef>
				<paramdef>string <parameter>funcimpl</parameter></paramdef>
			</funcprototype>
			</funcsynopsis>
			<para>
                Use this to dynamically register modifiers with Smarty. Pass in
                the Smarty modifier name, followed by the actual function name
                that it is mapped to.
			</para>
<example>
<title>register_modifier</title>
<programlisting>

// let's map PHP's stripslashes function to a Smarty modifier.

$smarty->register_modifier("sslash","stripslashes");

// now you can use {$var|sslash} to strip slashes from variables

</programlisting>
</example>
		</sect2>
		<sect2 id="api.clear.cache">
			<title>clear_cache</title>
			<funcsynopsis>
			<funcprototype>
			<funcdef>void <function>clear_cache</function></funcdef>
				<paramdef>string <parameter>template</parameter></paramdef>
				<paramdef>string <parameter>cache id</parameter></paramdef>
			</funcprototype>
			</funcsynopsis>
			<para>
                This clears the cache for the specified template. If you have
                multiple caches for this template, you can clear a specific
                cache by supplying the cache id as the second parameter. See the
                <link linkend="section.caching">caching section</link> for more
                information. This was added to Smarty 1.3.0.
			</para>
<example>
<title>clear_cache</title>
<programlisting>

// clear the cache for a template
$smarty->clear_cache("index.tpl");

// clear the cache for a particular cache id in an multiple-cache template
$smarty->clear_cache("index.tpl","CACHEID");


</programlisting>
</example>
		</sect2>
		<sect2 id="api.clear.all.cache">
			<title>clear_all_cache</title>
			<funcsynopsis>
			<funcprototype>
			<funcdef>void <function>clear_all_cache</function></funcdef>
				<paramdef><parameter></parameter></paramdef>
			</funcprototype>
			</funcsynopsis>
			<para>
				This clears the entire template cache. This was added to Smarty
				1.3.0.
			</para>
<example>
<title>clear_all_cache</title>
<programlisting>

// clear the entire cache
$smarty->clear_all_cache();


</programlisting>
</example>
		</sect2>
		<sect2 id="api.is.cached">
			<title>is_cached</title>
			<funcsynopsis>
			<funcprototype>
			<funcdef>void <function>is_cached</function></funcdef>
				<paramdef>string <parameter>template</parameter></paramdef>
				<paramdef>[string <parameter>cache_id</parameter>]</paramdef>
			</funcprototype>
			</funcsynopsis>
			<para>
                This returns true if there is a valid cache for this template.
                This only works if <link
                linkend="setting.caching">caching</link> is set to true. This
                was added to Smarty 1.3.0.
			</para>
<example>
<title>is_cached</title>
<programlisting>

$smarty->caching = true;

if(!$smarty->is_cached("index.tpl")) {
    // do database calls, assign vars here
}

$smarty->display("index.tpl");

</programlisting>
</example>
            <para>
                You can also pass a cache id as an an optional second parameter
                in the case you want multiple caches for the given template.
            </para>
<example>
<title>is_cached with multiple-cache template</title>
<programlisting>

$smarty->caching = true;

if(!$smarty->is_cached("index.tpl","FrontPage")) {
    // do database calls, assign vars here
}

$smarty->display("index.tpl","FrontPage");

</programlisting>
</example>
		</sect2>
		<sect2 id="api.get.template.vars">
			<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>
<example>
<title>get_template_vars</title>
<programlisting>

// get all assigned template vars
$tpl_vars = $smarty->get_template_vars();

// take a look at them
var_dump($tpl_vars);

</programlisting>
</example>
		</sect2>
		<sect2 id="api.display">
			<title>display</title>
			<funcsynopsis>
			<funcprototype>
			<funcdef>void <function>display</function></funcdef>
				<paramdef>string <parameter>template</parameter></paramdef>
				<paramdef>string <parameter>cache id</parameter></paramdef>
			</funcprototype>
			</funcsynopsis>
			<para>
				This displays the template. Supply a path relative to the
				<link linkend="setting.template.dir">template directory</link>.
                As an optional second parameter, you can pass a cache id.
                See the <link linkend="section.caching">caching section</link> for
                more information.
			</para>
<example>
<title>display</title>
<programlisting>

include("Smarty.class.php");
$smarty = new Smarty;


// only do db calls if cache doesn't exist
if(!$smarty->is_cached("index.tpl"))
{

    // 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");
</programlisting>
</example>
		</sect2>
		<sect2 id="api.fetch">
			<title>fetch</title>
			<funcsynopsis>
			<funcprototype>
			<funcdef>string <function>fetch</function></funcdef>
				<paramdef>string <parameter>template</parameter></paramdef>
				<paramdef>[string <parameter>cache_id</parameter>]</paramdef>
			</funcprototype>
			</funcsynopsis>
			<para>
                This returns the template output instead of displaying it.
                Supply a path relative to the <link
                linkend="setting.template.dir">template directory</link>
			</para>
<example>
<title>fetch</title>
<programlisting>

include("Smarty.class.php");
$smarty = new Smarty;


// only do db calls if cache doesn't exist
if(!$smarty->is_cached("index.tpl"))
{

    // 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);

}

// capture the output
$output = $smarty->fetch("index.tpl");

// do something with $output here

echo $output;

</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.
&lt;p&gt;
Your last login was on {$lastLoginDate}.

OUTPUT:

Hello Doug, glad to see you could make it.
&lt;p&gt;
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}&lt;br&gt;
{$Contacts.email}&lt;br&gt;
{* you can print arrays of arrays as well *}
{$Contacts.phone.home}&lt;br&gt;
{$Contacts.phone.cell}&lt;br&gt;

OUTPUT:

555-222-9876&lt;br&gt;
zaphod@slartibartfast.com&lt;br&gt;
555-444-3333&lt;br&gt;
555-111-1234&lt;br&gt;



</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>

&lt;html&gt;
&lt;title&gt;{#pageTitle#}&lt;/title&gt;
&lt;body bgcolor="{#bodyBgColor#}"&gt;
&lt;table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}"&gt;
	&lt;tr bgcolor="{#rowBgColor#}"&gt;
		&lt;td&gt;First&lt;/td&gt;
		&lt;td&gt;Last&lt;/td&gt;
		&lt;td&gt;Address&lt;/td&gt;
	&lt;/tr&gt;
&lt;/table&gt;
&lt;/body&gt;
&lt;/html&gt;
</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, &lt;font color="{#fontColor#}"&gt;{$name}!&lt;/font&gt;
{/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#}

&lt;SELECT name=company&gt;
{html_options values=$vals selected=$selected output=$output}
&lt;/SELECT&gt;
</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 *}
&lt;SELECT name=company&gt;
{html_options values=$vals selected=$selected output=$output}
&lt;/SELECT&gt;
</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 place 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"}

&lt;html&gt;
&lt;title&gt;{#pageTitle#}&lt;/title&gt;
&lt;body bgcolor="{#bodyBgColor#}"&gt;
&lt;table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}"&gt;
	&lt;tr bgcolor="{#rowBgColor#}"&gt;
		&lt;td&gt;First&lt;/td&gt;
		&lt;td&gt;Last&lt;/td&gt;
		&lt;td&gt;Address&lt;/td&gt;
	&lt;/tr&gt;
&lt;/table&gt;
&lt;/body&gt;
&lt;/html&gt;
</programlisting>
</example>
			<para>
            Config files may also contain sections. You can load variables from
            within a section with the added attribute
            <emphasis>section</emphasis>.
			</para>
            <para>
            NOTE: <emphasis>Config file sections</emphasis> and the built-in
            template function called <emphasis>section</emphasis> have nothing
            to do with each other, they just happen to share a common naming
            convention.
            </para>
<example>
<title>function config_load with section</title>
<programlisting>

{config_load file="colors.conf" section="Customer"}

&lt;html&gt;
&lt;title&gt;{#pageTitle#}&lt;/title&gt;
&lt;body bgcolor="{#bodyBgColor#}"&gt;
&lt;table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}"&gt;
	&lt;tr bgcolor="{#rowBgColor#}"&gt;
		&lt;td&gt;First&lt;/td&gt;
		&lt;td&gt;Last&lt;/td&gt;
		&lt;td&gt;Address&lt;/td&gt;
	&lt;/tr&gt;
&lt;/table&gt;
&lt;/body&gt;
&lt;/html&gt;
</programlisting>
</example>
		</sect2>
		<sect2>
			<title>include</title>
			<para>
            Include tags are used for including other templates in the current
            template. Any variables available in the current template are also
            available within the included 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.
            Any variables explicitly passed to an included template as
            attributes are only available within the scope of the included
            file. Attribute variables override current template variables, in
            the case they are named alike.
			</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 id="function.insert">
			<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.
			</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>
            TECHNICAL NOTE: It is possible to have portions of the template not
            cached. If you have <link linkend="section.caching">caching</link>
            turned on, insert tags will not be cached. They will run
            dynamically every time the page is created, even within cached
            pages. This works good for things like banners, polls, live
            weather, search results, 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 <emphasis>if</emphasis> must be paired with an
			<emphasis>/if</emphasis>. <emphasis>else</emphasis> and
			<emphasis>elseif</emphasis> 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, and must be separated from surrounding elements by
            spaces.
			</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}

{* same as above *}
{if $name == "Fred" || $name == "Wilma"}
	...
{/if}

{* the following syntax will NOT work, conditional qualifiers
   must be separated from surrounding elements by spaces *}
{if $name=="Fred" || $name=="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}

{* 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}
	&lt;script language=javascript&gt;

        	&lt;!--
                	function isblank(field) {
                	if (field.value == '') 
                        	{ return false; }
                	else
                        	{
                        	document.loginform.submit();
                        	return true;
                        	}
                	}
        	// --&gt;

	&lt;/script&gt;
{/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
            <emphasis>section</emphasis> tags must be paired with
            <emphasis>/section</emphasis> tags. Required parameters are
            <emphasis>name</emphasis> and <emphasis>loop</emphasis>. 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
            (usually an array of values) 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 (/). If you are using an associative array, separate the key
            and value with a period (.). <emphasis>sectionelse</emphasis> 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}&lt;br&gt;
{/section}

OUTPUT:

id: 1000&lt;br&gt;
id: 1001&lt;br&gt;
id: 1002&lt;br&gt;

</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}&lt;br&gt;
	name: {$customer/name}&lt;br&gt;
	address: {$customer/address}&lt;br&gt;
	&lt;p&gt;
{/section}


OUTPUT:

id: 1000&lt;br&gt;
name: John Smith&lt;br&gt;
address: 253 N 45th&lt;br&gt;
&lt;p&gt;
id: 1001&lt;br&gt;
name: Jack Jones&lt;br&gt;
address: 417 Mulberry ln&lt;br&gt;
&lt;p&gt;
id: 1002&lt;br&gt;
name: Jane Munson&lt;br&gt;
address: 5605 apple st&lt;br&gt;
&lt;p&gt;

</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}&lt;br&gt;
	name: {$mydata/name}&lt;br&gt;
	address: {$mydata/address}&lt;br&gt;
	&lt;p&gt;
{/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}&lt;br&gt;
	name: {$customer/name}&lt;br&gt;
	address: {$customer/address}&lt;br&gt;
	{section name=contact loop=$customer/contact_type}
		{$customer/contact/contact_type}: {$customer/contact/contact_info}&lt;br&gt;
	{/section}
	&lt;p&gt;
{/section}


OUTPUT:

id: 1000&lt;br&gt;
name: John Smith&lt;br&gt;
address: 253 N 45th&lt;br&gt;
home phone: 555-555-5555&lt;br&gt;
cell phone: 555-555-5555&lt;br&gt;
e-mail: john@mydomain.com&lt;br&gt;
&lt;p&gt;
id: 1001&lt;br&gt;
name: Jack Jones&lt;br&gt;
address: 417 Mulberry ln&lt;br&gt;
home phone: 555-555-5555&lt;br&gt;
cell phone: 555-555-5555&lt;br&gt;
e-mail: jack@mydomain.com&lt;br&gt;
&lt;p&gt;
id: 1002&lt;br&gt;
name: Jane Munson&lt;br&gt;
address: 5605 apple st&lt;br&gt;
home phone: 555-555-5555&lt;br&gt;
cell phone: 555-555-5555&lt;br&gt;
e-mail: jane@mydomain.com&lt;br&gt;
&lt;p&gt;


</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}
	name: {$customer/contacts.name}&lt;br&gt;
	home: {$customer/contacts.home}&lt;br&gt;
	cell: {$customer/contacts.cell}&lt;br&gt;
	e-mail: {$customer/contacts.email}&lt;p&gt;
{/section}


OUTPUT:

name: John Smith&lt;br&gt;
home: 555-555-5555&lt;br&gt;
cell: 555-555-5555&lt;br&gt;
e-mail: john@mydomain.com&lt;p&gt;
name: Jack Jones&lt;br&gt;
home phone: 555-555-5555&lt;br&gt;
cell phone: 555-555-5555&lt;br&gt;
e-mail: jack@mydomain.com&lt;p&gt;
name: Jane Munson&lt;br&gt;
home phone: 555-555-5555&lt;br&gt;
cell phone: 555-555-5555&lt;br&gt;
e-mail: jane@mydomain.com&lt;p&gt;


</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}&lt;br&gt;
{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}&lt;br&gt;
{/section}


OUTPUT:

0 id: 1000&lt;br&gt;
1 id: 1001&lt;br&gt;
2 id: 1002&lt;br&gt;

</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}&lt;br&gt;
{/section}


OUTPUT:

1 id: 1000&lt;br&gt;
2 id: 1001&lt;br&gt;
3 id: 1002&lt;br&gt;

</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}&lt;br&gt;
{/section}

There were {%customer.loop%} customers shown above.

OUTPUT:

0 id: 1000&lt;br&gt;
1 id: 1001&lt;br&gt;
2 id: 1002&lt;br&gt;

There were 3 customers shown above.

</programlisting>
</example>
			</sect3>
			<sect3>	
			<title>show</title>
			<para>
            <emphasis>show</emphasis> is used as a parameter to section.
            <emphasis>show</emphasis> 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}&lt;br&gt;
{/section}

{if %customer.show%}
	the section was shown.
{else}
	the section was not shown.
{/if}


OUTPUT:

1 id: 1000&lt;br&gt;
2 id: 1001&lt;br&gt;
3 id: 1002&lt;br&gt;

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}
&lt;table border=0&gt;
	&lt;tr&gt;
		&lt;td&gt;
			&lt;A HREF="{$url}"&gt;
			&lt;font color="red"&gt;This is a test&lt;/font&gt;
			&lt;/A&gt;
		&lt;/td&gt;
	&lt;/tr&gt;
&lt;/table&gt;
{/strip}


OUTPUT:

&lt;table border=0&gt;&lt;tr&gt;&lt;td&gt;&lt;A HREF="http://my.domain.com"&gt;&lt;font color="red"&gt;This is a test&lt;/font&gt;&lt;/A&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;

</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.
		</para>
		<sect2>
			<title>html_options</title>
            <informaltable frame=all>
                <tgroup cols=3>
                <colspec colname=param>
                <colspec colname=type>
                <colspec colname=required>
                <colspec colname=default>
                <colspec colname=desc>
                <thead>
                    <row>
                        <entry>Attribute Name</entry>
                        <entry>Type</entry>
                        <entry>Required</entry>       
                        <entry>Default</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>values</entry>
                        <entry>array</entry>
                        <entry>Yes, unless using options attribute</entry>
                        <entry><emphasis>n/a</emphasis></entry>
                        <entry>an array of values for dropdown</entry>
                    </row>
                    <row>
                        <entry>output</entry>
                        <entry>array</entry>
                        <entry>Yes, unless using options attribute</entry>
                        <entry><emphasis>n/a</emphasis></entry>
                        <entry>an array of output for dropdown</entry>
                    </row>
                    <row>
                        <entry>selected</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry><emphasis>empty</emphasis></entry>
                        <entry>the selected array element</entry>
                    </row>
                    <row>
                        <entry>options</entry>
                        <entry>associative array</entry>
                        <entry>Yes, unless using values and output</entry>
                        <entry><emphasis>n/a</emphasis></entry>
                        <entry>an associative array of values and output</entry>
                    </row>
                </tbody>
                </tgroup>
            </informaltable>
			<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. Required attributes are values
            and output, unless you use options instead.
			</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 *}

&lt;select name=customer_id&gt;
	{html_options values=$cust_ids selected=$customer_id output=$cust_names}
&lt;/select&gt;


{* an alternative method is to pass the values & output as an associative array into
   options. $customer_options is an associative array in this example. This
   functionality was added to Smarty 1.3.0 *}

&lt;select name=customer_id&gt;
	{html_options options=$customer_options selected=$customer_id}
&lt;/select&gt;


OUTPUT:

&lt;select name=customer_id&gt;
	&lt;option value="1000">Joe Schmoe&lt;option&gt;
	&lt;option value="1001" selected>Jack Smith&lt;option&gt;
	&lt;option value="1002">Jane Johnson&lt;option&gt;
	&lt;option value="1003">Charlie Brown&lt;option&gt;
&lt;/select&gt;

</programlisting>
</example>
		</sect2>
		<sect2>
			<title>html_select_date</title>
            <informaltable frame=all>
                <tgroup cols=3>
                <colspec colname=param>
                <colspec colname=type>
                <colspec colname=required>
                <colspec colname=default>
                <colspec colname=desc>
                <thead>
                    <row>
                        <entry>Attribute Name</entry>
                        <entry>Type</entry>
                        <entry>Required</entry>       
                        <entry>Default</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>prefix</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry>Date_</entry>
                        <entry>what to prefix the var name with</entry>
                    </row>
                    <row>
                        <entry>time</entry>
                        <entry>timestamp</entry>
                        <entry>No</entry>
                        <entry>current time</entry>
                        <entry>what date/time to use</entry>
                    </row>
                    <row>
                        <entry>start_year</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry>current year</entry>
                        <entry>the first year in the dropdown</entry>
                    </row>
                    <row>
                        <entry>end_year</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry>same as start_year</entry>
                        <entry>the last year in the dropdown</entry>
                    </row>
                    <row>
                        <entry>display_days</entry>
                        <entry>boolean</entry>
                        <entry>No</entry>
                        <entry>true</entry>
                        <entry>whether to display days or not</entry>
                    </row>
                    <row>
                        <entry>display_months</entry>
                        <entry>boolean</entry>
                        <entry>No</entry>
                        <entry>true</entry>
                        <entry>whether to display months or not</entry>
                    </row>
                    <row>
                        <entry>display_years</entry>
                        <entry>boolean</entry>
                        <entry>No</entry>
                        <entry>true</entry>
                        <entry>whether to display years or not</entry>
                    </row>
                    <row>
                        <entry>month_format</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry>%B</entry>
                        <entry>what format the month should be in (strftime)</entry>
                    </row>
                    <row>
                        <entry>day_format</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry>%02d</entry>
                        <entry>what format the day should be in (sprintf)</entry>
                    </row>
                    <row>
                        <entry>year_as_text</entry>
                        <entry>boolean</entry>
                        <entry>No</entry>
                        <entry>false</entry>
                        <entry>whether or not to display the year as text</entry>
                    </row>
                </tbody>
                </tgroup>
            </informaltable>
			<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.
			</para>
<example>
<title>html_select_date</title>
<programlisting>

{html_select_date}


OUTPUT:

&lt;select name="Date_Month"&gt;
&lt;option value="1"&gt;January&lt;/option&gt;
&lt;option value="2"&gt;February&lt;/option&gt;
&lt;option value="3"&gt;March&lt;/option&gt;
&lt;option value="4"&gt;April&lt;/option&gt;
&lt;option value="5"&gt;May&lt;/option&gt;
&lt;option value="6"&gt;June&lt;/option&gt;
&lt;option value="7"&gt;July&lt;/option&gt;
&lt;option value="8"&gt;August&lt;/option&gt;
&lt;option value="9"&gt;September&lt;/option&gt;
&lt;option value="10"&gt;October&lt;/option&gt;
&lt;option value="11"&gt;November&lt;/option&gt;
&lt;option value="12" selected&gt;December&lt;/option&gt;
&lt;/select&gt;
&lt;select name="Date_Day"&gt;
&lt;option value="1"&gt;01&lt;/option&gt;
&lt;option value="2"&gt;02&lt;/option&gt;
&lt;option value="3"&gt;03&lt;/option&gt;
&lt;option value="4"&gt;04&lt;/option&gt;
&lt;option value="5"&gt;05&lt;/option&gt;
&lt;option value="6"&gt;06&lt;/option&gt;
&lt;option value="7"&gt;07&lt;/option&gt;
&lt;option value="8"&gt;08&lt;/option&gt;
&lt;option value="9"&gt;09&lt;/option&gt;
&lt;option value="10"&gt;10&lt;/option&gt;
&lt;option value="11"&gt;11&lt;/option&gt;
&lt;option value="12"&gt;12&lt;/option&gt;
&lt;option value="13" selected&gt;13&lt;/option&gt;
&lt;option value="14"&gt;14&lt;/option&gt;
&lt;option value="15"&gt;15&lt;/option&gt;
&lt;option value="16"&gt;16&lt;/option&gt;
&lt;option value="17"&gt;17&lt;/option&gt;
&lt;option value="18"&gt;18&lt;/option&gt;
&lt;option value="19"&gt;19&lt;/option&gt;
&lt;option value="20"&gt;20&lt;/option&gt;
&lt;option value="21"&gt;21&lt;/option&gt;
&lt;option value="22"&gt;22&lt;/option&gt;
&lt;option value="23"&gt;23&lt;/option&gt;
&lt;option value="24"&gt;24&lt;/option&gt;
&lt;option value="25"&gt;25&lt;/option&gt;
&lt;option value="26"&gt;26&lt;/option&gt;
&lt;option value="27"&gt;27&lt;/option&gt;
&lt;option value="28"&gt;28&lt;/option&gt;
&lt;option value="29"&gt;29&lt;/option&gt;
&lt;option value="30"&gt;30&lt;/option&gt;
&lt;option value="31"&gt;31&lt;/option&gt;
&lt;/select&gt;
&lt;select name="Date_Year"&gt;
&lt;option value="2001" selected&gt;2001&lt;/option&gt;
&lt;/select&gt;

</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:

&lt;select name="StartDateMonth"&gt;
&lt;option value="1"&gt;January&lt;/option&gt;
&lt;option value="2"&gt;February&lt;/option&gt;
&lt;option value="3"&gt;March&lt;/option&gt;
&lt;option value="4"&gt;April&lt;/option&gt;
&lt;option value="5"&gt;May&lt;/option&gt;
&lt;option value="6"&gt;June&lt;/option&gt;
&lt;option value="7"&gt;July&lt;/option&gt;
&lt;option value="8"&gt;August&lt;/option&gt;
&lt;option value="9"&gt;September&lt;/option&gt;
&lt;option value="10"&gt;October&lt;/option&gt;
&lt;option value="11"&gt;November&lt;/option&gt;
&lt;option value="12" selected&gt;December&lt;/option&gt;
&lt;/select&gt;
&lt;select name="StartDateYear"&gt;
&lt;option value="1999"&gt;1995&lt;/option&gt;
&lt;option value="1999"&gt;1996&lt;/option&gt;
&lt;option value="1999"&gt;1997&lt;/option&gt;
&lt;option value="1999"&gt;1998&lt;/option&gt;
&lt;option value="1999"&gt;1999&lt;/option&gt;
&lt;option value="2000" selected&gt;2000&lt;/option&gt;
&lt;option value="2001"&gt;2001&lt;/option&gt;
&lt;/select&gt;

</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>
            <para>
            You can also add custom functions programatically with the <link
            linkend="api.register.function">register_function API</link>.
            </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>.
        Variable modifiers alter variable contents before they are displayed to
        the template. 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>
<example>
<title>capitalize</title>
<programlisting>

{* this displays a variable, unmodified *}
{$articleTitle|capitalize}

OUTPUT:

POLICE BEGIN CAMPAIGN TO RUNDOWN JAYWALKERS

</programlisting>
</example>
		</sect2>
		<sect2 id="date.format">
			<title>date_format</title>
            <informaltable frame=all>
                <tgroup cols=3>
                <colspec colname=param>
                <colspec colname=type>
                <colspec colname=required>
                <colspec colname=default>
                <colspec colname=desc>
                <thead>
                    <row>
                        <entry>Parameter Position</entry>
                        <entry>Type</entry>
                        <entry>Required</entry>       
                        <entry>Default</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>1</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry>%b %e, %Y</entry>
                        <entry>This is the format for the outputted date.</entry>
                    </row>
                </tbody>
                </tgroup>
            </informaltable>
			<para>
            This formats a date and time 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.
			</para>
<example>
<title>date_format</title>
<programlisting>

{$currentDate|date_format}
{$currentDate|date_format:"%A, %B %e, %Y"}
{$currentDate|date_format:"%H:%M:%S"}

OUTPUT:

Feb 6, 2001
Tuesday, February 6, 2001
14:33:00

</programlisting>
</example>
<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) 

%g - Week-based year within century [00,99]

%G - Week-based year, including the century [0000,9999]

%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) 

%k - Hour (24-hour clock) single digits are preceded by a blank. (range 0 to 23)

%l - hour as a decimal number using a 12-hour clock, single digits preceeded by
a space (range 1 to 12)

%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 - day of the week as a decimal, Sunday being 0 

%W - week number of the current year as a decimal number, starting with the first Monday as the first day of the first week 

%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 


PROGRAMMERS NOTE: date_format is a wrapper to PHP's strftime() function. You
may have more or less conversion specifiers available depending on your
system's strftime() function where PHP was compiled. Check your system's manpage
for a full list of valid specifiers.
</programlisting>
</example>

		</sect2>
		<sect2>
			<title>default</title>
            <informaltable frame=all>
                <tgroup cols=3>
                <colspec colname=param>
                <colspec colname=type>
                <colspec colname=required>
                <colspec colname=default>
                <colspec colname=desc>
                <thead>
                    <row>
                        <entry>Parameter Position</entry>
                        <entry>Type</entry>
                        <entry>Required</entry>       
                        <entry>Default</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>1</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry><emphasis>empty</emphasis></entry>
                        <entry>This is the default value to output if the
                        variable is empty.</entry>
                    </row>
                </tbody>
                </tgroup>
            </informaltable>
			<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.
			</para>
<example>
<title>default</title>
<programlisting>

{* this will display "no title" (without the quotes) if $articleTitle is empty *}
{$articleTitle|default:"no title"}

OUTPUT:

no title

</programlisting>
</example>
		</sect2>
		<sect2>
			<title>escape</title>
            <informaltable frame=all>
                <tgroup cols=3>
                <colspec colname=param>
                <colspec colname=type>
                <colspec colname=required>
                <colspec colname=posvals>
                <colspec colname=default>
                <colspec colname=desc>
                <thead>
                    <row>
                        <entry>Parameter Position</entry>
                        <entry>Type</entry>
                        <entry>Required</entry>
                        <entry>Possible Values</entry>
                        <entry>Default</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>1</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry>html,url</entry>
                        <entry>html</entry>
                        <entry>This is the escape format to use.</entry>
                    </row>
                </tbody>
                </tgroup>
            </informaltable>
			<para>
			This is used to html or url escape a variable. By default,
			the variable is html escaped.
			</para>
<example>
<title>escape</title>
<programlisting>

{$articleTitle}
{$articleTitle|escape}
{$articleTitle|escape:"html"}
{$articleTitle|escape:"url"}

OUTPUT:

Stiff Opposition Expected to Casketless Funeral Plan
Stiff%20Opposition%20Expected%20to%20Casketless%20Funeral%20Plan
Stiff%20Opposition%20Expected%20to%20Casketless%20Funeral%20Plan
Stiff+Opposition+Expected+to+Casketless+Funeral+Plan

</programlisting>
</example>
		</sect2>
		<sect2>
			<title>lower</title>
			<para>
			This is used to lowercase a variable.
			</para>
<example>
<title>lower</title>
<programlisting>

{$articleTitle}
{$articleTitle|lower}

OUTPUT:

Two Convicts Evade Noose, Jury Hung.
two convicts evade noose, jury hung.

</programlisting>
</example>
		</sect2>
		<sect2>
			<title>replace</title>
            <informaltable frame=all>
                <tgroup cols=3>
                <colspec colname=param>
                <colspec colname=type>
                <colspec colname=required>
                <colspec colname=default>
                <colspec colname=desc>
                <thead>
                    <row>
                        <entry>Parameter Position</entry>
                        <entry>Type</entry>
                        <entry>Required</entry>
                        <entry>Default</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>1</entry>
                        <entry>string</entry>
                        <entry>Yes</entry>
                        <entry><emphasis>n/a</emphasis></entry>
                        <entry>This is the string of text to be replaced.</entry>
                    </row>
                    <row>
                        <entry>2</entry>
                        <entry>string</entry>
                        <entry>Yes</entry>
                        <entry><emphasis>n/a</emphasis></entry>
                        <entry>This is the string of text to replace with.</entry>
                    </row>
                </tbody>
                </tgroup>
            </informaltable>
			<para>
			A simple search and replace on a variable.
			</para>
<example>
<title>replace</title>
<programlisting>

{$articleTitle}
{$articleTitle|replace:"Garden":"Vineyard"}
{$articleTitle|replace:" ":"   "}

OUTPUT:

Child's Stool Great for Use in Garden.
Child's Stool Great for Use in Vineyard.
Child's   Stool   Great   for   Use   in   Garden.

</programlisting>
</example>
		</sect2>
		<sect2>
			<title>spacify</title>
            <informaltable frame=all>
                <tgroup cols=3>
                <colspec colname=param>
                <colspec colname=type>
                <colspec colname=required>
                <colspec colname=default>
                <colspec colname=desc>
                <thead>
                    <row>
                        <entry>Parameter Position</entry>
                        <entry>Type</entry>
                        <entry>Required</entry>
                        <entry>Default</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>1</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry><emphasis>one space</emphasis></entry>
                        <entry>This what gets inserted between each character of
                        the variable.</entry>
                    </row>
                </tbody>
                </tgroup>
            </informaltable>
			<para>
			spacify is a way to insert a space between every character of a variable.
			You can optionally pass a different character (or string) to insert.
			</para>
<example>
<title>spacify</title>
<programlisting>

{$articleTitle}
{$articleTitle|spacify}
{$articleTitle|spacify:"^^"}

OUTPUT:

Something Went Wrong in Jet Crash, Experts Say.
S o m e t h i n g   W e n t   W r o n g   i n   J e t   C r a s h ,   E x p e r t s   S a y .
S^^o^^m^^e^^t^^h^^i^^n^^g^^ ^^W^^e^^n^^t^^ ^^W^^r^^o^^n^^g^^ ^^i^^n^^ ^^J^^e^^t^^ ^^C^^r^^a^^s^^h^^,^^ ^^E^^x^^p^^e^^r^^t^^s^^ ^^S^^a^^y^^.

</programlisting>
</example>
		</sect2>
		<sect2>
			<title>string_format</title>
            <informaltable frame=all>
                <tgroup cols=3>
                <colspec colname=param>
                <colspec colname=type>
                <colspec colname=required>
                <colspec colname=default>
                <colspec colname=desc>
                <thead>
                    <row>
                        <entry>Parameter Position</entry>
                        <entry>Type</entry>
                        <entry>Required</entry>
                        <entry>Default</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>1</entry>
                        <entry>string</entry>
                        <entry>Yes</entry>
                        <entry><emphasis>n/a</emphasis></entry>
                        <entry>This is what format to use. (sprintf)</entry>
                    </row>
                </tbody>
                </tgroup>
            </informaltable>
			<para>
			This is a way to format strings, such as decimal numbers and such.
			Use the syntax for sprintf for the formatting.
			</para>
<example>
<title>string_format</title>
<programlisting>

{$number}
{$number|string_format:"%.2f"}
{$number|string_format:"%d"}

OUTPUT:

23.5787446
23.58
24

</programlisting>
</example>
		</sect2>
		<sect2>
			<title>strip_tags</title>
			<para>
			This strips out markup tags, basically anything between &lt; and &gt;.
			</para>
<example>
<title>strip_tags</title>
<programlisting>

{$articleTitle}
{$articleTitle|strip_tags}

OUTPUT:

Blind Woman Gets &lt;font face="helvetica"&gt;New Kidney&lt;/font&gt; from Dad she Hasn't Seen in &lt;b&gt;years&lt;/b&gt;.
Blind Woman Gets New Kidney from Dad she Hasn't Seen in years.

</programlisting>
</example>
		</sect2>
		<sect2>
			<title>truncate</title>
            <informaltable frame=all>
                <tgroup cols=3>
                <colspec colname=param>
                <colspec colname=type>
                <colspec colname=required>
                <colspec colname=default>
                <colspec colname=desc>
                <thead>
                    <row>
                        <entry>Parameter Position</entry>
                        <entry>Type</entry>
                        <entry>Required</entry>
                        <entry>Default</entry>
                        <entry>Description</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>1</entry>
                        <entry>integer</entry>
                        <entry>No</entry>
                        <entry>80</entry>
                        <entry>This determines how many characters to truncate
                        to.</entry>
                    </row>
                    <row>
                        <entry>2</entry>
                        <entry>string</entry>
                        <entry>No</entry>
                        <entry>...</entry>
                        <entry>This is the text to append if truncation occurs.</entry>
                    </row>
                    <row>
                        <entry>3</entry>
                        <entry>boolean</entry>
                        <entry>No</entry>
                        <entry>false</entry>
                        <entry>This determines whether or not to truncate at a
                        word boundary (false), or at the exact character (true).</entry>
                    </row>
                </tbody>
                </tgroup>
            </informaltable>
			<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>
<example>
<title>truncate</title>
<programlisting>

{$articleTitle}
{$articleTitle|truncate}
{$articleTitle|truncate:30}
{$articleTitle|truncate:30:""}
{$articleTitle|truncate:30:"---"}
{$articleTitle|truncate:30:"":true}
{$articleTitle|truncate:30:"...":true}

OUTPUT:

Two Sisters Reunite after Eighteen Years at Checkout Counter.
Two Sisters Reunite after Eighteen Years at Checkout Counter.
Two Sisters Reunite after...
Two Sisters Reunite after
Two Sisters Reunite after---
Two Sisters Reunite after Eigh
Two Sisters Reunite after E...

</programlisting>
</example>
		</sect2>
		<sect2>
			<title>upper</title>
			<para>
			This is used to uppercase a variable.
			</para>
<example>
<title>upper</title>
<programlisting>

{$articleTitle}
{$articleTitle|upper}

OUTPUT:

If Strike isn't Settled Quickly it may Last a While.
IF STRIKE ISN'T SETTLED QUICKLY IT MAY LAST A WHILE.

</programlisting>
</example>
		</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>			
            <para>
            You can also add modifiers programatically with the <link
            linkend="api.register.modifier">register_modifier API</link>.
            </para>
		</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.
        After that, the error consists of the actual line number in the Smarty
        class that the error occured.
		</para>
		
		<para>
        There are certain errors that Smarty cannot catch, such as missing
        close tags. These types of errors usually end up in PHP compile-time
        parsing errors.
		</para>

<example>
<title>PHP parsing 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 parsing error, the error line number will
        correspond to the compiled PHP script, not the template itself. 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 might have to 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="resources">
	<title>Resources</title>
	<para>
	Smarty's homepage is located at http://www.phpinsider.com/php/code/Smarty/.
	You can join the mailing list by sending an e-mail to
	subscribe-smarty@lists.ispi.net. An archive of the mailing list can be
	viewed at http://marc.theaimsgroup.com/ under www/smarty.
	</para>
</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 &lt;monte@ispi.net&gt;: Concepted compiling templates into PHP
    scripts, wrote initial "proof of concept" implementation, and maintains
    documentation.
	</para>
	<para>
    Andrei Zmievski &lt;andrei@ispi.net&gt;: Rewrote parser from scratch and
    added other features too numerous to mention.
	</para>
	<para>
    Anne Holz &lt;anne@ispi.net&gt;: Many of Smarty's formatting features were
    a direct result of needs from her department.
	</para>
	<para>
	Frank Kromann &lt;fmk@php.net&gt;: Idea of custom function ability.
	</para>
	<para>
    A special thanks goes to 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 the members of the php-template mailing list and
    the smarty mailing list, whom shared and brought many ideas to the table.
	</para>
	<para>
	Rasmus Lerdorf &lt;rasmus@php.net&gt;: For starting what eventually became
	the coolest programming language ever.
	</para>
</chapter>
</book>