mirror of
https://github.com/smarty-php/smarty.git
synced 2025-08-06 19:34:27 +02:00
update README
This commit is contained in:
monte.ohrt
279
README
279
README
@@ -56,9 +56,11 @@ 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.
|
||||
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 will be no longer necessary but
|
||||
is still supported for BC.
|
||||
|
||||
Examples:
|
||||
{$x+$y} will output the sum of x and y.
|
||||
{$foo = strlen($bar)} function in assignment
|
||||
@@ -66,79 +68,61 @@ Examples:
|
||||
{$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.
|
||||
Smarty tags can also be used inside double quoted strings.
|
||||
Example: {$foo="this is message {counter}"}
|
||||
|
||||
|
||||
|
||||
You can define arrays.
|
||||
You can define arrays within templates.
|
||||
Examples:
|
||||
{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 supported for assigning variables.
|
||||
Example: {$foo=$bar+2}
|
||||
|
||||
|
||||
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
|
||||
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.
|
||||
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 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.
|
||||
Example: {$foo[]=1}
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
You can now use a new PHP like syntax for accessing array elements.
|
||||
You can use a PHP-like syntax for accessing array elements, as well as the
|
||||
original "dot" notation.
|
||||
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
|
||||
{$foo[section_name]} smarty section access, not array access!
|
||||
|
||||
The old dot syntax stays intact for BC, but there are also some improvements.
|
||||
The original "dot" notation stays, and with 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
|
||||
|
||||
note that { and } are used to address ambiguties when nesting the dot syntax.
|
||||
|
||||
|
||||
Variable names itself can now be variable and contain expressions.
|
||||
Variable names themselves can be variable and contain expressions.
|
||||
Examples:
|
||||
$foo normal variable
|
||||
$foo normal variable
|
||||
$foo_{$bar} variable name containing other variable
|
||||
$foo_{$x+$y} variable name containing expressions
|
||||
$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.
|
||||
|
||||
|
||||
|
||||
{$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)}
|
||||
|
||||
|
||||
|
||||
Example: {$object->method1($x)->method2($y)}
|
||||
|
||||
{for} tag added for looping (replacement for {section} tag):
|
||||
{for $x=0, $y=count($foo); $x<$y; $i++} .... {/for}
|
||||
@@ -147,16 +131,17 @@ inital expression at {for}.
|
||||
|
||||
The Smarty 2 {section} syntax is still supported.
|
||||
|
||||
New shorter {foreach} syntax to loop over an array.
|
||||
Example: {foreach $myarray as $var}...{/foreach}
|
||||
|
||||
Within the foreach loop, properties are access via:
|
||||
|
||||
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
|
||||
$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
|
||||
|
||||
The Smarty 2 {foreach} tag syntax is still supported.
|
||||
|
||||
@@ -164,38 +149,27 @@ 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}
|
||||
|
||||
|
||||
|
||||
|
||||
while block tag is now implemented:
|
||||
{while $foo}...{/while}
|
||||
{while $x lt 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()}
|
||||
|
||||
There is a new {function}...{/function} block tag. This allows to reuse code
|
||||
sequences like a plugin function. It can all itself recursively.
|
||||
|
||||
|
||||
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.
|
||||
Example:
|
||||
|
||||
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}
|
||||
<li>{$entry@key}</li>
|
||||
{menu data=$entry level=$level+1}
|
||||
{else}
|
||||
<li>{$entry}</li>
|
||||
{/if}
|
||||
@@ -203,7 +177,8 @@ Template file:
|
||||
</ul>
|
||||
{/function}
|
||||
|
||||
{$menu = ['item1','item2','item3' => ['item3-1','item3-2','item3-3' => ['item3-3-1','item3-3-2']],'item4']}
|
||||
{$menu = ['item1','item2','item3' => ['item3-1','item3-2','item3-3' =>
|
||||
['item3-3-1','item3-3-2']],'item4']}
|
||||
|
||||
{menu data=$menu}
|
||||
|
||||
@@ -219,120 +194,119 @@ Generated output:
|
||||
+ 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.
|
||||
|
||||
|
||||
|
||||
|
||||
The function tag itself must have the "name" attribute. This name is 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.
|
||||
|
||||
|
||||
|
||||
{nocache}...{/nocache} will declare a section of the template to be non-cached
|
||||
when template caching is enabled.
|
||||
|
||||
New nocache attribute:
|
||||
You can declare variable/function output as non-cached with the nocache attribute.
|
||||
{$foo nocache=true} or {$foo nocache}
|
||||
Examples:
|
||||
|
||||
{foo bar="baz" nocache=true} or {foo bar="baz" nocache}
|
||||
{$foo nocache=true}
|
||||
{$foo nocache} /* same */
|
||||
|
||||
{time() nocache=true} or {time() nocache}
|
||||
{foo bar="baz" nocache=true}
|
||||
{foo bar="baz" nocache} /* same */
|
||||
|
||||
Or you can assign the variable already in your script as nocache:
|
||||
$smarty->assign('foo',$something,true);
|
||||
{$foo}
|
||||
{time() nocache=true}
|
||||
{time() nocache} /* same */
|
||||
|
||||
Or you can also assign the variable in your script as nocache:
|
||||
$smarty->assign('foo',$something,true); // third param is nocache setting
|
||||
{$foo} /* non-cached */
|
||||
|
||||
$smarty.current_dir returns the directory name of the current template.
|
||||
|
||||
$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 strings directly as templates with the "string" resource type.
|
||||
Examples:
|
||||
$smarty->display('string:This is my template, {$foo}!'); // php
|
||||
{include file="string:This is my template, {$foo}!"} // template
|
||||
|
||||
|
||||
|
||||
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
|
||||
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 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 <EFBFBD>chained<EFBFBD>. 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.
|
||||
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 the known Smarty assign<EFBFBD>. methods will work also on the data and template objects.
|
||||
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.
|
||||
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(<EFBFBD>foo<EFBFBD>,<2C>bar<EFBFBD>); // assign variable
|
||||
A Smarty data object can be created as follows:
|
||||
$data = new Smarty_Data; // create root data object
|
||||
$data->assign('foo','bar'); // assign variables as usual
|
||||
|
||||
$data= new Smarty_Data($smarty); // create data object having a parent link to the Smarty object
|
||||
$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
|
||||
$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.
|
||||
A template object can be created by using the createTemplate method. It has the
|
||||
same parameter assignments as the fetch() or display() method.
|
||||
Function definition:
|
||||
function createTemplate($template, $cache_id = null, $compile_id = null, $parent = null)
|
||||
|
||||
The first parameter can be a template name, a smarty object or a data object.
|
||||
|
||||
Examples:
|
||||
$tpl = $smarty->createTemplate(<EFBFBD>mytpl.tpl<EFBFBD>); // create template object not linked to any parent
|
||||
$tpl->assign(<EFBFBD>foo<EFBFBD>,<2C>bar<EFBFBD>); // assign variable
|
||||
$tpl = $smarty->createTemplate('mytpl.tpl'); // create template object not linked to any parent
|
||||
$tpl->assign('foo','bar'); // directly assign variables
|
||||
|
||||
$tpl = $smarty->createTemplate(<EFBFBD>mytpl.tpl<EFBFBD>,$smarty); // create template having a parent link to the Smarty object
|
||||
$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
|
||||
|
||||
$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, the template object
|
||||
is will link back to the Smarty object as it's parent.
|
||||
|
||||
If a template is called by an {include...} tag from another template, the
|
||||
subtemplate links back to the calling template as it's parent.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
Examples:
|
||||
{assign var=foo value=<EFBFBD>bar<EFBFBD>} // no scope is specified, the default <EFBFBD>local<EFBFBD> will apply. Values can only be
|
||||
// seen in the current template
|
||||
{$foo=<3D>bar<61>}
|
||||
{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=<EFBFBD>bar<EFBFBD> scope=parent} // Values will be exported to the parent object
|
||||
// (normally the calling template)
|
||||
{$foo=<3D>bar<61> scope=parent}
|
||||
{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=<EFBFBD>bar<EFBFBD> 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='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=<EFBFBD>bar<EFBFBD> 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}
|
||||
{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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
@@ -344,6 +318,20 @@ object instance. The Smarty 2 function-style plugins are still compatible, you
|
||||
can drop them right into the Smarty 3 plugin directory.
|
||||
|
||||
|
||||
TEMPLATE INHERITANCE:
|
||||
=====================
|
||||
|
||||
(to be filled in)
|
||||
|
||||
PHP STREAMS:
|
||||
============
|
||||
|
||||
(to be filled in)
|
||||
|
||||
VARIBLE FILTERS:
|
||||
================
|
||||
|
||||
(to be filled in)
|
||||
|
||||
PHP TEMPLATES
|
||||
=============
|
||||
@@ -370,14 +358,13 @@ In PHP templates, assigned vars are available simply as:
|
||||
<?php echo $foo; ?>
|
||||
<?=$foo?> // php short tags
|
||||
|
||||
You can't use Smarty modifiers from the plugin folder.
|
||||
They must be implemented as PHP function.
|
||||
At this point, smarty modifier/function plugins are not
|
||||
conveniently accessible from PHP templates. A wrapper
|
||||
function may become available in the future.
|
||||
|
||||
You can call PHP functions a usual:
|
||||
<?php echo foo($bar); ?>
|
||||
|
||||
|
||||
|
||||
Please look through it and send any questions/suggestions/etc to the forums.
|
||||
|
||||
http://www.phpinsider.com/smarty-forum/viewtopic.php?t=14168
|
||||
|
||||
Reference in New Issue
Block a user