Smarty For Template Designers

Chapter 3. Basic Syntax

All Smarty template tags are enclosed within delimiters. By default, these delimiters are { and }, but they can be changed.

For these examples, we will assume that you are using the default delimiters. In Smarty, all content outside of delimiters is displayed as static content, or unchanged. When Smarty encounters template tags, it attempts to interpret them, and displays the appropriate output in their place.

{* Smarty *}

{* include the header file here *}
{include file="header.tpl"}

{include file=$includeFile}

{include file=#includeFile#}

{* display dropdown lists *}
<select name="company">
{html_options values=$vals selected=$selected output=$output}
</select>

Variables

Template variables start with a dollar sign. They can contain numbers, letters and underscores, much like a PHP variable. You can reference arrays that are indexed numerically or non-numerically. You can also reference object properties and methods. Config file variables are an exception to the dollar sign syntax. They can be referenced with surrounding hashmarks, or with the special $smarty.config variable.

{$foo}        <-- displaying a simple variable (non array/object)
{$foo[4]}     <-- display the 5th element of a zero-indexed array
{$foo.bar}    <-- display the "bar" key value of an array, similar to PHP $foo['bar']
{$foo.$bar}   <-- display variable key value of an array, similar to PHP $foo[$bar]
{$foo->bar}   <-- display the object property "bar"
{$foo->bar()} <-- display the return value of object method "bar"
{#foo#}       <-- display the config file variable "foo"
{$smarty.config.foo} <-- synonym for {#foo#}
{$foo[bar]}   <-- syntax only valid in a section loop, see {section}

Many other combinations are allowed

{$foo.bar.baz}
{$foo.$bar.$baz}
{$foo[4].baz}
{$foo[4].$baz}
{$foo.bar.baz[4]}
{$foo->bar($baz,2,$bar)} <-- passing parameters
{"foo"}       <-- static values are allowed

Functions

Each Smarty tag either prints a variable or invokes some sort of function. Functions are processed and displayed by enclosing the function and its attributes into delimiters like so: {funcname attr1="val" attr2="val"}.

{config_load file="colors.conf"}

{include file="header.tpl"}

{if $highlight_name}
    Welcome, <font color="{#fontColor#}">{$name}!</font>
{else}
    Welcome, {$name}!
{/if}

{include file="footer.tpl"}

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 additional functions implemented via plugins. They can be modified to your liking, or you can add new ones. html_options and html_select_date are examples of custom functions.

Attributes

Most of the functions take attributes that specify or modify their behavior. Attributes to Smarty functions are much like HTML attributes. Static values don't have to be enclosed in quotes, but it is recommended for literal strings. Variables may also be used, and should not be in quotes.

Some attributes require boolean values (true or false). These can be specified as either unquoted true, on, and yes, or false, off, and no.

{include file="header.tpl"}

{include file=$includeFile}

{include file=#includeFile#}

{html_select_date display_days=yes}

<select name="company">
{html_options values=$vals selected=$selected output=$output}
</select>

Embedding Vars in Double Quotes

Smarty will recognize assigned variables embedded in double quotes so long as the variables contain only numbers, letters, underscores and brackets []. With any other characters (period, object reference, etc.) the variable must be surrounded by backticks. You cannot embed modifiers, they must always be applied outside of quotes.

SYNTAX EXAMPLES:
{func var="test $foo test"}       <-- sees $foo
{func var="test $foo_bar test"}   <-- sees $foo_bar
{func var="test $foo[0] test"}    <-- sees $foo[0]
{func var="test $foo[bar] test"}  <-- sees $foo[bar]
{func var="test $foo.bar test"}   <-- sees $foo (not $foo.bar)
{func var="test `$foo.bar` test"} <-- sees $foo.bar
{func var="test `$foo.bar` test"|escape} <-- modifiers outside quotes!

PRACTICAL EXAMPLES:
{include file="subdir/$tpl_name.tpl"} <-- will replace $tpl_name with value
{cycle values="one,two,`$smarty.config.myval`"} <-- must have backticks

Math

Math can be applied directly to variable values.

{$foo+1}

{$foo*$bar}

{* some more complicated examples *}

{$foo->bar-$bar[1]*$baz->foo->bar()-3*7}

{if ($foo+$bar.test%$baz*134232+10+$b+10)}

{$foo|truncate:"`$fooTruncCount/$barTruncFactor-1`"}

{assign var="foo" value="`$foo+$bar`"}

Escaping Smarty Parsing

It is sometimes desirable or even necessary to have Smarty ignore sections it would otherwise parse. A classic example is embedding Javascript or CSS code in a template. The problem arises as those languages use the { and } characters which are also the default delimiters for Smarty.

The simplest thing is to avoid the situation altogether by separating your Javascript and CSS code into their own files and then using standard HTML methods to access them.

Including literal content is possible using {literal} .. {/literal} blocks. Similar to HTML entity usage, you can use {ldelim},{rdelim} or {$smarty.ldelim},{$smarty.rdelim} to display the current delimiters.

It is often convenient to simply change Smarty's $left_delimiter and $right_delimiter.

Where example.tpl is:

<script language="javascript">
var foo = <!--{$foo}-->;
function dosomething() {
    alert("foo is " + foo);
}
dosomething();
</script>