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.
capture
capture is used to collect the output of the template
into a variable instead of displaying it. Any content between {capture
name="foo"} and {/capture} is collected into the variable specified in the
name attribute. The captured content can be used in the template from the
special variable $smarty.capture.foo where foo is the value passed in the
name attribute. If you do not supply a name attribute, then "default" will
be used. All {capture} commands must be paired with {/capture}. You can nest
capture commands.
Technical Note: Smarty 1.4.0 - 1.4.4 placed the captured
content into the variable named $return. As of 1.4.5, this behavior
was changed to use the name attribute, so update your templates
accordingly.
| Caution |
| Be careful when capturing
insert output. If you have caching turned on and you have
insert commands that you expect to run
within cached content, do not capture this content. |
Example 7-1. capturing template content
{* we don't want to print a table row unless content is displayed *}
{capture name=banner}
{include file="get_banner.tpl"}
{/capture}
{if $smarty.capture.banner ne ""}
<tr>
<td>
{$smarty.capture.banner}
</td>
</tr>
{/if}
|
|
config_load
This function is used for loading in variables from a configuration file
into the template. See Config Files for more info.
Example 7-2. function config_load
{config_load file="colors.conf"}
<html>
<title>{#pageTitle#}</title>
<body bgcolor="{#bodyBgColor#}">
<table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}">
<tr bgcolor="{#rowBgColor#}">
<td>First</td>
<td>Last</td>
<td>Address</td>
</tr>
</table>
</body>
</html>
|
|
Config files may also contain sections. You can load variables from
within a section with the added attribute
section.
Note: Config
file sections and the built-in template function called
section have
nothing to do with each other, they just happen to share a common
naming convention.
Example 7-3. function config_load with section
{config_load file="colors.conf" section="Customer"}
<html>
<title>{#pageTitle#}</title>
<body bgcolor="{#bodyBgColor#}">
<table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}">
<tr bgcolor="{#rowBgColor#}">
<td>First</td>
<td>Last</td>
<td>Address</td>
</tr>
</table>
</body>
</html>
|
|
foreach,foreachelse
foreach
loops are an alternative to
section loops. foreach
is used to loop over a single associative array. The syntax for
foreach is much easier
than section, but as a
tradeoff it can only be used for a single array.
foreach tags must be paired with
/foreach tags.
Required parameters are from
and item. The name of
the foreach loop can be anything you like, made up of letters, numbers and
underscores. foreach
loops can be nested, and the nested foreach names must be unique from each
other. The from
variable (usually an array of values) determines the number of times
foreach will loop.
foreachelse is
executed when there are no values in the
from variable.
Example 7-4. foreach
{* this example will print out all the values of the $custid array *}
{foreach from=$custid item=curr_id}
id: {$curr_id}<br>
{/foreach}
OUTPUT:
id: 1000<br>
id: 1001<br>
id: 1002<br>
|
|
Example 7-5. foreach key
{* The key contains the key for each looped value
assignment looks like this:
$smarty->assign("contacts", array(array("phone" => "1", "fax" => "2", "cell" => "3"),
array("phone" => "555-4444", "fax" => "555-3333", "cell" => "760-1234")));
*}
{foreach name=outer item=contact from=$contacts}
{foreach key=key item=item from=$contact}
{$key}: {$item}<br>
{/foreach}
{/foreach}
OUTPUT:
phone: 1<br>
fax: 2<br>
cell: 3<br>
phone: 555-4444<br>
fax: 555-3333<br>
cell: 760-1234<br>
|
|
Foreach-loops also have their
own variables that handle foreach properties. These are indicated like so:
{$smarty.foreach.foreachname.varname} with foreachname being the name
specified as the name
attribute of foreach
iteration
iteration is used to
display the current loop iteration.
Iteration always starts
with 1 and is incremented by one one each iteration.
first
first is set to true if the current
foreach iteration is the first one.
last
last is set to true if the current
foreach iteration is the last one.
show
show is used as a parameter to foreach.
show is a boolean
value, true or false. If false, the foreach will not be displayed. If
there is a foreachelse present, that will be alternately displayed.
total
total is used to display the number of
iterations that this foreach will loop. This can be used inside or after
the foreach.
include
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 template resource path.
You can optionally pass the
assign attribute, which will specify a template variable name
that the output of include
will be assigned to instead of displayed.
Example 7-6. function include
{include file="header.tpl"}
{* body of template goes here *}
{include file="footer.tpl"}
|
|
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.
Example 7-7. function include passing variables
{include file="header.tpl" title="Main Menu" table_bgcolor="#c0c0c0"}
{* body of template goes here *}
{include file="footer.tpl" logo="http://my.example.com/logo.gif"}
|
|
Use the syntax for template resources to include files outside of the $template_dir
directory.
Example 7-8. function include template resource examples
{* absolute filepath *}
{include file="/usr/local/include/templates/header.tpl"}
{* absolute filepath (same thing) *}
{include file="file:/usr/local/include/templates/header.tpl"}
{* windows absolute filepath (MUST use "file:" prefix) *}
{include file="file:C:/www/pub/templates/header.tpl"}
{* include from template resource named "db" *}
{include file="db:header.tpl"}
|
|
include_php
Technical Note: include_php is pretty much
deprecated from Smarty, you can accomplish the same functionality
via a custom template function. The only reason to use include_php
is if you really have a need to quarantine the php function away
from the plugin directory or your application code. See the
componentized template example for details.
include_php tags are used to include a php script in your
template. If security is enabled, then the php script must be located in the
$trusted_dir path. The include_php tag must have the attribute "file", which
contains the path to the included php file, either relative to $trusted_dir,
or an absolute path.
include_php is a nice way to handle componentized
templates, and keep PHP code separate from the template files. Lets say you
have a template that shows your site navigation, which is pulled dynamically
from a database. You can keep your PHP logic that grabs database content in
a separate directory, and include it at the top of the template. Now you can
include this template anywhere without worrying if the database information
was assigned by the application before hand.
By default, php files are only included once even if
called multiple times in the template. You can specify that it should be
included every time with the once
attribute. Setting once to false will include the php script each time it is
included in the template.
You can optionally pass the
assign attribute, which will specify a
template variable name that the output of
include_php will be assigned to instead of
displayed.
The smarty object is available as $this within the PHP script that you
include.
Example 7-9. function include_php
load_nav.php
-------------
<?php
// load in variables from a mysql db and assign them to the template
require_once("MySQL.class.php");
$sql = new MySQL;
$sql->query("select * from site_nav_sections order by name",SQL_ALL);
$this->assign('sections',$sql->record);
?>
index.tpl
---------
{* absolute path, or relative to $trusted_dir *}
{include_php file="/path/to/load_nav.php"}
{foreach item="curr_section" from=$sections}
<a class="blue" HREF="p_{$curr_section.url}">{$curr_section.name}</a><br>
{/foreach}
|
|
insert
Insert tags work much like include tags, except that insert tags are not
cached when you have template caching enabled. They will be executed on
every invocation of the template.
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, and we don't want this
contents cached with the page. 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 contents.
Example 7-10. function insert
{* example of fetching a banner *}
{insert name="getBanner" lid=#banner_location_id# sid=#site_id#}
|
|
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("lid" => "12345","sid" => "67890")); and display the
returned results in place of the insert tag.
If you supply the "assign" attribute, the output of the
insert tag will be assigned to this template variable instead of being
output to the template. NOTE: assigning the output to a template variable
isn't too useful with caching enabled.
If you supply the "script" attribute, this php script
will be included (only once) before the insert function is executed. This is
the case where the insert function may not exist yet, and a php script must
be included first to make it work. The path can be either absolute, or
relative to $trusted_dir. When security is enabled, the script must reside
in $trusted_dir.
The Smarty object is passed as the second argument. This
way you can reference and modify information in the Smarty object from
within the insert function.
Technical Note: It is possible to have
portions of the template not cached. If you have caching 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.
if,elseif,else
{if}
statements in Smarty have much the same flexibility as PHP if statements,
with a few added features for the template engine. Every
{if} must be paired
with an {/if}.
{else} and
{elseif} are also
permitted. All PHP conditionals are recognized, such as
||,
or,
&&,
and, etc.
The following is a list of recognized qualifiers, which must be separated
from surrounding elements by spaces. Note that items listed in [brackets]
are optional. PHP equivalents are shown where applicable.
Example 7-11. if statements
{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 embed 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}
|
|
ldelim and rdelim are used for escaping template delimiters, in our case "{"
or "}". You can also use{literal}{/literal} to escape blocks of text. See also {$smarty.ldelim}and{$smarty.rdelim}
Literal tags allow a block of data to be taken literally.
This is typically used around javascript or stylesheet blocks where curly braces
would interfere with the template delimiter syntax. Anything within
{literal}{/literal} tags is not interpreted, but displayed as-is. If you need
template tags embedded in your literal block, consider using {ldelim}{rdelim} to escape the individual delimiters instead.
php tags allow php to be embedded directly into the template. They will not
be escaped, regardless of the $php_handling setting. This is for advanced users
only, not normally needed.