This article shows the major changes in smarty 3.
The Smarty 3 API has been refactored for a better consistency and modularity. The Smarty 2 API syntax is still supported, but will throw a deprecation notice. The Smarty 3 API is a bit different. Many Smarty 2 API calls are deprecated but still work. You will want to update your calls to Smarty 3 for maximum efficiency.
General
– Smarty 3 is PHP 5 only. It will not work with PHP 4.
– The {php} tag is disabled by default. Enable with $smarty->allow_php_tag=true.
– Delimiters surrounded by whitespace are no longer treated as Smarty tags.
Therefore, { foo } will not compile as a tag, you must use {foo}.
This change Makes Javascript/CSS easier to work with, eliminating the need for {literal}. This can be disabled by setting smarty->auto_literal = false;
– All Smarty methods now follow the “fooBarBaz” camel case syntax.
– All Smarty properties now have getters and setters. For example, the property $smarty->cache_dir can be set with $smarty->setCacheDir(‘foo/’) and can be retrieved with $smarty->getCacheDir().
Plugins
A lot of Smarty 3 core functionality lies in the sysplugins directory. You do not need to change any files here.
The plugins/ folder is where Smarty plugins are located. You can add your own here, or create a separate plugin directory, just the same as Smarty 2.
Smarty3 are following the same coding rules as in Smarty2. The only difference is that the template object is passed as additional third parameter.
smarty_plugintype_name (array $params, object $smarty, object $template).
The Smarty 2 plugins are still compatible as long as they do not make use of specific Smarty2 internals.
Template inheritance
With template inheritance you can define blocks, which are areas that can be overriden by child templates, so your templates could look like this:
parent.tpl:
[codesyntax lang=”php”]
<html>
<head>
{block name=’title’}My site name{/block}
< / head >
< body >
< h1 >{block name=’page-title’}Default page title{/block}< / h1 >
< div id=”content” >
{block name=’content’}
Default content
{/block}
< /div >
< /body >
< /html >
[/codesyntax]
child.tpl:
[codesyntax lang=”php”]
{extends file=’parent.tpl’}
{block name=’title’}
Child title
{/block}
[/codesyntax]
grandchild.tpl:
[codesyntax lang=”php”]
{extends file=’child.tpl’}
{block name=’title’}Home – {$smarty.block.parent}{/block}
{block name=’page-title’}My home{/block}
{block name=’content’}
{foreach $images as $img}
< img src=”{$img.url}” alt=”{$img.description}” / >
{/foreach}
{/block}
[/codesyntax]
LEXER/PARSER
Smarty 3 now uses a lexing tokenizer for its parser/compiler. Basically, this means Smarty has some syntax additions that make life easier such as in-template math, shorter/intuitive function parameter options, infinite function recursion, more accurate error handling, etc.
Expressions
Smarty 3 allows expressions almost anywhere. Expressions can include PHP functions as long as they are not disabled by the security policy, object methods and properties, etc. The {math} plugin is no longer necessary but is still supported for BC.
[codesyntax lang=”php”]
{$x+$y} will output the sum of x and y.
{$foo = strlen($bar)} function in assignment
{assign var=foo value= $x+$y} in attributes
{$foo = myfunct( ($x+$y)*3 )} as function parameter
{$foo[$x+3]} as array index
[/codesyntax]
Tags can be used as values within other tags or inside double quoted strings.
[codesyntax lang=”php”]
{$foo={counter}+3}
{$foo=”this is message {counter}”}
[/codesyntax]
Expressions in variable names
Note that { and } are used to address ambiguties when nesting the dot syntax.
Variable names themselves can be variable and contain expressions.
[codesyntax lang=”php”]
$foo normal variable
$foo_{$bar} variable name containing other variable
$foo_{$x+$y} variable name containing expressions
$foo_{$bar}_buh_{$blar} variable name with multiple segments
{$foo_{$x}} will output the variable
$foo_1 if $x has a value of 1.
[/codesyntax]
Arrays
You can define arrays within templates.
[codesyntax lang=”php”]
{assign var=foo value=[1,2,3]}
{assign var=foo value=['y'=>'yellow','b'=>'blue']}
Nested arrays:
{assign var=foo value=[1,[9,8],3]}
[/codesyntax]
You can assign a value to a specific array element. If the variable exists but is not an array, it is converted to an array before the new values are assigned.
[codesyntax lang=”php”]
{$foo['bar']=1}
{$foo['bar']['blar']=1}
[/codesyntax]
You can append values to an array. If the variable exists but is not an array, it is converted to an array before the new values are assigned.
[codesyntax lang=”php”]
{$foo[]=1}
[/codesyntax]
You can use a PHP-like syntax for accessing array elements, as well as the original “dot” notation.
[codesyntax lang=”php”]
{$foo[1]} normal access
{$foo['bar']} {$foo['bar'][1]} {$foo[$x+$x]} index may contain any expression
{$foo[$bar[1]]} nested index
{$foo[section_name]} smarty section access, not array access!
[/codesyntax]
The original “dot” notation stays, and with improvements.
[codesyntax lang=”php”]
{$foo.a.b.c} => $foo[‘a’][‘b’][‘c’]
{$foo.a.$b.c} => $foo[‘a’][$b][‘c’] with variable index
{$foo.a.{$b+4}.c} => $foo[‘a’][$b+4][‘c’] with expression as index
{$foo.a.{$b.c}} => $foo[‘a’][$b[‘c’]] with nested index
[/codesyntax]
Object method chaining
[codesyntax lang=”php”]
{$object->method1($x)->method2($y)}
[/codesyntax]
Cycles
for
{for} tag added for looping (replacement for {section} tag)
[codesyntax lang=”php”]
{for $x=0, $y=count($foo); $x<$y; $x++}
….
{/for}
[/codesyntax]
Foreach
A shorter syntax for ‘foreach’. The Smarty 2 {foreach} tag syntax is still supported.
[codesyntax lang=”php”]
{foreach $myarray as $var}
…
{/foreach}
[/codesyntax]
Within the foreach loop, properties are access via:
[codesyntax lang=”php”]
$var@key foreach $var array key
$var@iteration foreach current iteration count (1,2,3…)
$var@index foreach current index count (0,1,2…)
$var@total foreach $var array total
$var@first true on first iteration
$var@last true on last iteration
[/codesyntax]
NOTE: {$bar[foo]} still indicates a variable inside of a {section} named foo. If you want to acces s an array element with index foo, you must use quotes such as {$bar[‘foo’]}, or use the dot syntax {$bar.foo}.
while
while block tag is now implemented:
[codesyntax lang=”php”]
{while $foo}…{/while}
{while $x lt 10}…{/while}
[/codesyntax]
Direct access to PHP functions
Just as you can use PHP functions as modifiers directly, you can now access PHP functions directly, provided they are permitted by security settings:
[codesyntax lang=”php”]
{time()}
[/codesyntax]
There is a new {function}…{/function} block tag to implement a template function. This enables reuse of code sequences like a plugin function. It can call itself recursively.
Template function must be called with the new {call…} tag.
[codesyntax lang=”php”]
{function level=0}
<ul>
{foreach $data as $entry}
{if is_array($entry)}
<li>{$entry@key}</li>
{call data=$entry level=$level+1}{else}
<li>{$entry}</li>
{/if}
{/foreach}
</ul>
{/function}
{$menu = [‘item1′,’item2′,’item3’ => [‘item3-1′,’item3-2′,’item3-3’ =>
[‘item3-3-1′,’item3-3-2′]],’item4’]}{call data=$menu}
[/codesyntax]
VARIABLE SCOPE / VARIABLE STORAGE
In Smarty 2, all assigned variables were stored within the Smarty object. Therefore, all variables assigned in PHP were accessible by all subsequent fetch and display template calls. In Smarty 3, we have the choice to assign variables to the main Smarty object, to user-created data objects, and to user-created template objects. These objects can be chained. The object at the end of a chain can access all variables belonging to that template and all variables within the parent objects. The Smarty object can only be the root of a chain, but a chain can be isolated from the Smarty object. All known Smarty assignment interfaces will work on the data and template objects. Besides the above mentioned objects, there is also a special storage area for global variables. A Smarty data object can be created as follows: [codesyntax lang=”php”]
$data = $smarty->createData(); // create root data objec
t$data->assign(‘foo’,’bar’); // assign variables as usual
$data->config_load(‘my.conf’); // load config file
$data= $smarty->createData($smarty); // create data object having a parent link to the Smarty object
$data2= $smarty->createData($data); // create data object having a parent link to the
$data data object
[/codesyntax]
A template object can be created by using the createTemplate method. It has the same parameter assignments as the fetch() or display() method. [codesyntax lang=”php”]
function createTemplate($template, $cache_id = null, $compile_id = null, $parent = null)
[/codesyntax]
The first parameter can be a template name, a smarty object or a data object.
[codesyntax lang=”php”]
$tpl = $smarty->createTemplate(‘mytpl.tpl’); // create template object not linked to any parent
$tpl->assign(‘foo’,’bar’); // directly assign variables
$tpl->config_load(‘my.conf’); // load config file
$tpl = $smarty->createTemplate(‘mytpl.tpl’,$smarty); // create template having a parent link to the Smarty object
$tpl = $smarty->createTemplate(‘mytpl.tpl’,$data); // create template having a parent link to the $data object
[/codesyntax]
The standard fetch() and display() methods will implicitly create a template object. If the $parent parameter is not specified in these method calls, the template object is will link back to the Smarty object as it’s parent.
Variable visibility from a parent template
If a template is called by an {include…} tag from another template, the subtemplate links back to the calling template as it’s parent.
All variables assigned locally or from a parent template are accessible. If the template creates or modifies a variable by using the {assign var=foo…} or {$foo=…} tags, these new values are only known locally (local scope). When the template exits, none of the new variables or modifications can be seen in the parent template(s). This is same behavior as in Smarty 2.
Scope attribute
With Smarty 3, we can assign variables with a scope attribute which allows the availablility of these new variables or modifications globally (ie in the parent templates.) Possible scopes are local, parent, root and global. The scope attribute can also be attached to the {include…} tag. In this case, the specified scope will be the default scope for all assignments within the included template.
[codesyntax lang=”php”]
{assign var=foo value='bar'} // no scope is specified, the default 'local'
{$foo='bar'} // same, local scope
{assign var=foo value='bar' scope='local'} // same, local scope
{assign var=foo value='bar' scope='parent'} // Values will be available to the parent object
{$foo='bar' scope='parent'} // (normally the calling template)
{assign var=foo value='bar' scope='root'} // Values will be exported up to the root object, so they can
{$foo='bar' scope='root'} // be seen from all templates using the same root.
{assign var=foo value='bar' scope='global'} // Values will be exported to global variable storage,
{$foo='bar' scope='global'} // they are available to any and all templates.
[/codesyntax]
References: