mirror of
https://github.com/smarty-php/smarty.git
synced 2025-08-06 19:34:27 +02:00
- update of README
This commit is contained in:
Uwe.Tews
373
README
373
README
@@ -45,20 +45,308 @@ backward compatible with Smarty 2, except for the following items:
|
||||
There are many things that are new to Smarty 3. Here are the notable items:
|
||||
|
||||
LEXER/PARSER
|
||||
============
|
||||
|
||||
Smarty 3 now uses a lexing tokenizer for it's 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.
|
||||
|
||||
|
||||
WHAT IS NEW IN SMARTY TEMPLATE SYNTAX
|
||||
=====================================
|
||||
|
||||
Smarty 3 allows to use 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 will be no longer necessary but is still active for BC.
|
||||
Examples:
|
||||
{$x+$y} will output the sum of x and y.
|
||||
{$foo = strlen($bar)} function in assignment
|
||||
{assign var=foo value= $x+$y} in attributs
|
||||
{$foo = myfunct( ($x+$y)*3 )} as function parameter
|
||||
{$foo[$x+3]} as array index
|
||||
|
||||
The {math} plugin will be no longer necessary but is still active for BC.
|
||||
|
||||
|
||||
|
||||
Smarty tags can be used as values within other tags.
|
||||
Example: {$foo={counter}+3}
|
||||
|
||||
They can also be used inside double quoted strings.
|
||||
Example: {$foo="this is message {counter}"}
|
||||
|
||||
|
||||
|
||||
You can define arrays.
|
||||
{assign var=foo value=[1,2,3]}
|
||||
{assign var=foo value=['y'=>'yellow','b'=>'blue']}
|
||||
Arrays can be nested.
|
||||
{assign var=foo value=[1,[9,8],3]}
|
||||
|
||||
|
||||
|
||||
There is a new "short" syntax for assigning variables.
|
||||
{$foo=$bar+2}
|
||||
|
||||
You can assign a value to a specific array element. If the variable does exists but is not
|
||||
an array it is converted to an array before the new values are assigned
|
||||
Examples:
|
||||
{$foo['bar']=1}
|
||||
{$foo['bar']['blar']=1}
|
||||
|
||||
You can append values to an array. If the variable does exists but is not an array it is
|
||||
converted to an array before the new values are assigned.
|
||||
{$foo[]=1}
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
You can now use a new PHP like syntax for accessing array elements.
|
||||
Examples:
|
||||
{$foo[1]} normal access
|
||||
{$foo['bar']}
|
||||
{$foo['bar'][1]}
|
||||
{$foo[section_name]} unquoted strings will result in an access using a section index
|
||||
{$foo[$x+$x]} index may contain any expression
|
||||
{$foo[$bar[1]]} nested index
|
||||
|
||||
The old dot syntax stays intact for BC, but there are also some improvements.
|
||||
Examples:
|
||||
{$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
|
||||
{ and } are used to address ambiguties
|
||||
when nesting the dot syntax
|
||||
|
||||
|
||||
|
||||
Variable names itself can now be variable and contain expressions.
|
||||
Examples:
|
||||
$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.
|
||||
|
||||
|
||||
|
||||
|
||||
Object method chaining is implemented.
|
||||
{$object->method1($x)->method2($y)}
|
||||
|
||||
|
||||
|
||||
|
||||
{for} tag added for looping (replacement for {section} tag):
|
||||
{for $x=0, $y=count($foo); $x<$y; $i++} .... {/for}
|
||||
Any number of statements can be used separated by comma as the first
|
||||
inital expression at {for}.
|
||||
|
||||
The Smarty 2 {section} syntax is still supported.
|
||||
|
||||
|
||||
|
||||
New {foreach} syntax to loop over an array:
|
||||
{foreach $myarray as $var} .... {/foreach}
|
||||
$var@key will deliver the key
|
||||
$var@iteration will deliver the iteration
|
||||
$var@index will deliver the index
|
||||
$var@total will deliver the total number of array entries
|
||||
$var@first will deliver true for the first iteration
|
||||
$var@last will deliver true for the last iteration
|
||||
|
||||
The Smarty 2 {foreach} tag syntax is still supported.
|
||||
|
||||
NOTE: {$bar[foo]} still indicates a variable inside of a {section} named foo.
|
||||
If you want to access an array element with index foo, you must use quotes
|
||||
such as {$bar['foo']}, or use the dot syntax {$bar.foo}.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
There is a new while block tag
|
||||
{while $foo == true} ..... {/while}
|
||||
{while $row = mysql_assoc($mysql_result)} ..... {/while}
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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:
|
||||
{time()}
|
||||
|
||||
|
||||
|
||||
There is a new {function} {/function} block tag.
|
||||
This allows to reuse code sequences like a function.
|
||||
It can all itself recursively.
|
||||
|
||||
See the following example for e nested menu ouput.
|
||||
|
||||
Template file:
|
||||
{function name=menu level=0}
|
||||
<ul class="level{$level}">
|
||||
{foreach $data as $entry}
|
||||
{if is_array($entry)}
|
||||
<li>{$entry@key}</li>
|
||||
{menu 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']}
|
||||
|
||||
{menu data=$menu}
|
||||
|
||||
|
||||
Generated output:
|
||||
* item1
|
||||
* item2
|
||||
* item3
|
||||
o item3-1
|
||||
o item3-2
|
||||
o item3-3
|
||||
+ item3-3-1
|
||||
+ item3-3-2
|
||||
* item4
|
||||
|
||||
The function tag itself must have name attribute. This name will become the tag name when calling
|
||||
the function. The function tag may have any number of additional attributes. These will be default
|
||||
settings for local variables.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
New {nocache} block function:
|
||||
{nocache} ... {/nocache} will declare a section of the template to be not cached.
|
||||
|
||||
|
||||
|
||||
|
||||
New nocache attribute:
|
||||
You can declare variable/function output as non-cached with the nocache attribute.
|
||||
{$foo nocache=true} or {$foo nocache}
|
||||
|
||||
{foo bar="baz" nocache=true} or {foo bar="baz" nocache}
|
||||
|
||||
{time() nocache=true} or {time() nocache}
|
||||
|
||||
Or you can assign the variable already in your script as nocache:
|
||||
$smarty->assign('foo',$something,true);
|
||||
{$foo}
|
||||
|
||||
|
||||
|
||||
$smarty.current_dir returns the dirname of the current template.
|
||||
|
||||
|
||||
|
||||
|
||||
You can use strings directly as templates with the "string" resource type:
|
||||
$smarty->display('string:This is my template, {$foo}!');
|
||||
{include file="string:This is my template, {$foo}!"}
|
||||
|
||||
|
||||
|
||||
VARIABLE SCOPE / VARIABLE STORAGE
|
||||
=================================
|
||||
|
||||
In Smarty 2 all Smarty variables were stored within the Smarty object.
|
||||
So all variables assigned by the PHP script were accessible by all subsequent
|
||||
fetch and display template calls.
|
||||
|
||||
In Smarty 3 we do have the possibility to assign variables to the Smarty object,
|
||||
to user created data objects and to user created template objects.
|
||||
These objects can be <20>chained<65>. A template object which normally will always be at
|
||||
the end of such a chain can access all variables belonging to that template and
|
||||
all variables within the parent chain. The Smarty object can only be the root
|
||||
of such a chain, but a chain can also be isolated from the Smarty root.
|
||||
|
||||
All the known Smarty assign<67>. methods will work also on the data and template objects.
|
||||
|
||||
Besides the above mentioned objects there is also a special storage area for global variables.
|
||||
|
||||
A data object can be created as follow:
|
||||
$data = new Smarty_Data; // create root data object not linked to any parent
|
||||
$data->assign(<28>foo<6F>,<2C>bar<61>); // assign variable
|
||||
|
||||
$data= new Smarty_Data($smarty); // create data object having a parent link to the Smarty object
|
||||
|
||||
$data2= new Smarty_Data($data); // create data object having a parent link to the $data data object
|
||||
|
||||
|
||||
A template object can be created by using the createTemplate method. It has the same parameter as the fetch or display method.
|
||||
function createTemplate($template, $cache_id = null, $compile_id = null, $parent = null)
|
||||
|
||||
Examples:
|
||||
$tpl = $smarty->createTemplate(<28>mytpl.tpl<70>); // create template object not linked to any parent
|
||||
$tpl->assign(<28>foo<6F>,<2C>bar<61>); // assign variable
|
||||
|
||||
$tpl = $smarty->createTemplate(<28>mytpl.tpl<70>,$smarty); // create template having a parent link to the Smarty object
|
||||
|
||||
$tpl = $smarty->createTemplate(<28>mytpl.tpl<70>,$data); // create template having a parent link to the $data object
|
||||
|
||||
|
||||
The standard fetch and display methods will implicitly create a template object. If the $parent parameter is not
|
||||
specified in these method calls for BC reasons the template object is linked back to the Smarty object as parent.
|
||||
|
||||
If a template is called by an {include..} tag from another template the subtemplate links back to the calling
|
||||
template as parent.
|
||||
|
||||
As said before from inside a template all variables can be accessed which are defined locally or within the parent chain.
|
||||
If the template code does create or modify a variable by using the {assign var=foo<6F>} or {$foo=<3D>} tags these new values
|
||||
are know only locally (local scope). So when the template exits none of the new variables or modifications can be seen
|
||||
in the calling template. This is same behavior as in Smarty 2.
|
||||
|
||||
With Smarty3 we can assign variables with a scope attribute which allows to export new variables or modifications
|
||||
into the outside world when a template exits.
|
||||
|
||||
Possible scopes are local, parent, root and global.
|
||||
Examples:
|
||||
{assign var=foo value=<3D>bar<61>} // no scope is specified, the default <20>local<61> will apply. Values can only be
|
||||
// seen in the current template
|
||||
{$foo=<3D>bar<61>}
|
||||
|
||||
{assign var=foo value=<3D>bar<61> scope=parent} // Values will be exported to the parent object
|
||||
// (normally the calling template)
|
||||
{$foo=<3D>bar<61> scope=parent}
|
||||
|
||||
{assign var=foo value=<3D>bar<61> scope=root} // Values will be exported to the root object, so they can
|
||||
// be seen from all templates using the same root.
|
||||
{$foo=<3D>bar<61> scope=root}
|
||||
|
||||
{assign var=foo value=<3D>bar<61> scope=global} // Values will be exported to the global variable storage,
|
||||
//so they can be seen from all templates.
|
||||
{$foo=<3D>bar<61> scope=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.
|
||||
|
||||
|
||||
|
||||
PLUGINS
|
||||
=======
|
||||
|
||||
Smarty 3 plugins are now objects that extend Smarty_Internal_PluginBase. All
|
||||
plugins have the property $this->smarty available as a reference to the Smarty
|
||||
object instance. The Smarty 2 function-style plugins are still compatible, you
|
||||
can drop them right into the Smarty 3 plugin directory.
|
||||
|
||||
|
||||
|
||||
PHP TEMPLATES
|
||||
=============
|
||||
|
||||
For those that prefer pure PHP over the {tag} based syntax, Smarty now offers
|
||||
a PHP option for template syntax. PHP templates have several differences over
|
||||
@@ -89,91 +377,6 @@ You can call PHP functions a usual:
|
||||
<?php echo foo($bar); ?>
|
||||
|
||||
|
||||
WHAT IS NEW IN SMARTY TEMPLATE SYNTAX
|
||||
|
||||
Smarty tags can be used as values within other tags.
|
||||
Example: {$foo={counter}+3}
|
||||
|
||||
They can also be used inside double quoted strings.
|
||||
Example: {$foo="this is message {counter}"}
|
||||
|
||||
$smarty.current_dir returns the dirname of the current template.
|
||||
|
||||
You can use strings directly as templates with the "string" resource type:
|
||||
$smarty->display('string:This is my template, {$foo}!');
|
||||
{include file="string:This is my template, {$foo}!"}
|
||||
|
||||
You can use math expressions in the templates.
|
||||
{$x+$y} will output the sum of x and y.
|
||||
PHP functions can be used in expressions unless they are disabled by the security policy.
|
||||
{assign var=foo value=2*(3+sqrt($bar))}
|
||||
|
||||
You can define arrays.
|
||||
{assign var=foo value=[1,2,3]}
|
||||
{assign var=foo value=['y'=>'yellow','b'=>'blue']}
|
||||
Arrays can be nested.
|
||||
{assign var=foo value=[1,[9,8],3]}
|
||||
|
||||
There is a new "short" syntax for assigning variables.
|
||||
{$foo=$bar+2}
|
||||
{$foo['y']='yellow}
|
||||
{$foo[]=$bar}
|
||||
|
||||
Arrays can be accessed now also with a new syntax.
|
||||
{$foo['bar']} // same as {$foo.bar}
|
||||
The quotes are required. This syntax addition addresses ambiguties when nesting
|
||||
the dot syntax. The dot syntax {$foo.bar} will still work.
|
||||
You can use array elements as index of other array.
|
||||
{$foo['bar'][$blar['buh']['puh']}
|
||||
{$foo.bar.{$blar.buh}.puh}
|
||||
|
||||
Variable names can be handled with variables directly.
|
||||
{$foo_{$x}} will output the variable $foo_1 if $x has a value of 1.
|
||||
|
||||
Object method chaining is implemented.
|
||||
{$object->method1($x)->method2($y)}
|
||||
|
||||
{for} tag added for looping (replacement for {section} tag):
|
||||
{for $x=0, $y=count($foo); $x<$y; $i++} .... {/for}
|
||||
Any number of statements can be used separated by comma as the first
|
||||
inital expression at {for}.
|
||||
|
||||
The Smarty 2 {section} syntax is still supported.
|
||||
|
||||
New {foreach} syntax to loop over an array:
|
||||
{foreach $myarray as $var} .... {/foreach}
|
||||
$var@key will deliver the key
|
||||
$var@iteration will deliver the iteration
|
||||
$var@index will deliver the index
|
||||
$var@total will deliver the total number of array entries
|
||||
$var@first will deliver true for the first iteration
|
||||
$var@last will deliver true for the last iteration
|
||||
|
||||
The Smarty 2 {foreach} tag syntax is still supported.
|
||||
|
||||
NOTE: {$bar[foo]} still indicates a variable inside of a {section} named foo.
|
||||
If you want to access an array element with index foo, you must use quotes
|
||||
such as {$bar['foo']}, or use the dot syntax {$bar.foo}.
|
||||
|
||||
New {while....} tag:
|
||||
{while $i<10} .... {/while}
|
||||
|
||||
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:
|
||||
{time()}
|
||||
|
||||
New {nocache} block function:
|
||||
{nocache} ... {/nocache} will declare a section of the template to be not cached.
|
||||
|
||||
New nocache attribute:
|
||||
You can declare variable/function output as non-cached with the nocache attribute.
|
||||
{$foo nocache=true} or {$foo nocache}
|
||||
{foo bar="baz" nocache=true} or {foo bar="baz" nocache}
|
||||
{time() nocache=true} or {time() nocache}
|
||||
Or you can assign the variable already in your script as nocache:
|
||||
$smarty->assign('foo',$something,true);
|
||||
{$foo}
|
||||
|
||||
Please look through it and send any questions/suggestions/etc to the forums.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user