smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-08-07 11:54:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

update README

Browse Source
This commit is contained in:
monte.ohrt
2009-11-02 21:14:10 +00:00
parent 15ee358dd7
commit 6eb95b0b30
1 changed files with 133 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

279
README
View File

@@ -56,9 +56,11 @@ more accurate error handling, etc.
WHAT IS NEW IN SMARTY TEMPLATE SYNTAX WHAT IS NEW IN SMARTY TEMPLATE SYNTAX
===================================== =====================================
Smarty 3 allows to use expressions almost anywhere. Expressions can include PHP functions as Smarty 3 allows expressions almost anywhere. Expressions can include PHP
long as they are not disabled by the security policy, object methods and properties etc. functions as long as they are not disabled by the security policy, object
The {math} plugin will be no longer necessary but is still active for BC. methods and properties, etc. The {math} plugin will be no longer necessary but
is still supported for BC.
Examples: Examples:
{$x+$y} will output the sum of x and y. {$x+$y} will output the sum of x and y.
{$foo = strlen($bar)} function in assignment {$foo = strlen($bar)} function in assignment
@@ -66,79 +68,61 @@ Examples:
{$foo = myfunct( ($x+$y)*3 )} as function parameter {$foo = myfunct( ($x+$y)*3 )} as function parameter
{$foo[$x+3]} as array index {$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. Smarty tags can be used as values within other tags.
Example: {$foo={counter}+3} 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}"} Example: {$foo="this is message {counter}"}
You can define arrays within templates.
Examples:
You can define arrays.
{assign var=foo value=[1,2,3]} {assign var=foo value=[1,2,3]}
{assign var=foo value=['y'=>'yellow','b'=>'blue']} {assign var=foo value=['y'=>'yellow','b'=>'blue']}
Arrays can be nested. Arrays can be nested.
{assign var=foo value=[1,[9,8],3]} {assign var=foo value=[1,[9,8],3]}
There is a new short syntax supported for assigning variables.
Example: {$foo=$bar+2}
You can assign a value to a specific array element. If the variable exists but
There is a new "short" syntax for assigning variables. is not an array, it is converted to an array before the new values are assigned.
{$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: Examples:
{$foo['bar']=1} {$foo['bar']=1}
{$foo['bar']['blar']=1} {$foo['bar']['blar']=1}
You can append values to an array. If the variable does exists but is not an array it is You can append values to an array. If the variable exists but is not an array,
converted to an array before the new values are assigned. it is converted to an array before the new values are assigned.
{$foo[]=1} Example: {$foo[]=1}
You can use a PHP-like syntax for accessing array elements, as well as the
original "dot" notation.
You can now use a new PHP like syntax for accessing array elements.
Examples: Examples:
{$foo[1]} normal access {$foo[1]} normal access
{$foo['bar']} {$foo['bar']}
{$foo['bar'][1]} {$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[$x+$x]} index may contain any expression
{$foo[$bar[1]]} nested index {$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: Examples:
{$foo.a.b.c} => $foo['a']['b']['c'] {$foo.a.b.c} => $foo['a']['b']['c']
{$foo.a.$b.c} => $foo['a'][$b]['c'] with variable index {$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+4}.c} => $foo['a'][$b+4]['c'] with expression as index
{$foo.a.{$b.c}} => $foo['a'][$b['c']] with nested 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 themselves can be variable and contain expressions.
Variable names itself can now be variable and contain expressions.
Examples: Examples:
$foo normal variable $foo normal variable
$foo_{$bar} variable name containing other 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_{$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 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} tag added for looping (replacement for {section} tag):
{for $x=0, $y=count($foo); $x<$y; $i++} .... {/for} {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. 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: $var@key foreach $var array key
{foreach $myarray as $var} .... {/foreach} $var@iteration foreach current iteration count (1,2,3...)
$var@key will deliver the key $var@index foreach current index count (0,1,2...)
$var@iteration will deliver the iteration $var@total foreach $var array total
$var@index will deliver the index $var@first true on first iteration
$var@total will deliver the total number of array entries $var@last true on last iteration
$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. 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 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}. such as {$bar['foo']}, or use the dot syntax {$bar.foo}.
while block tag is now implemented:
{while $foo}...{/while}
{while $x lt 10}...{/while}
There is a new while block tag
{while $foo == true} ..... {/while}
{while $row = mysql_assoc($mysql_result)} ..... {/while}
Direct access to PHP functions: Direct access to PHP functions:
Just as you can use PHP functions as modifiers directly, you can now access Just as you can use PHP functions as modifiers directly, you can now access
PHP functions directly, provided they are permitted by security settings: PHP functions directly, provided they are permitted by security settings:
{time()} {time()}
There is a new {function}...{/function} block tag. This allows to reuse code
sequences like a plugin function. It can all itself recursively.
Example:
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: Template file:
{function name=menu level=0} {function name=menu level=0}
<ul class="level{$level}"> <ul class="level{$level}">
{foreach $data as $entry} {foreach $data as $entry}
{if is_array($entry)} {if is_array($entry)}
<li>{$entry@key}</li> <li>{$entry@key}</li>
{menu data=$entry level=$level+1} {menu data=$entry level=$level+1}
{else} {else}
<li>{$entry}</li> <li>{$entry}</li>
{/if} {/if}
@@ -203,7 +177,8 @@ Template file:
</ul> </ul>
{/function} {/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} {menu data=$menu}
@@ -219,120 +194,119 @@ Generated output:
+ item3-3-2 + item3-3-2
* item4 * item4
The function tag itself must have name attribute. This name will become the tag name when calling The function tag itself must have the "name" attribute. This name is the tag
the function. The function tag may have any number of additional attributes. These will be default name when calling the function. The function tag may have any number of
settings for local variables. additional attributes. These will be default settings for local variables.
New {nocache} block function: 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: New nocache attribute:
You can declare variable/function output as non-cached with the 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: {time() nocache=true}
$smarty->assign('foo',$something,true); {time() nocache} /* same */
{$foo}
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.
Examples:
$smarty->display('string:This is my template, {$foo}!'); // php
{include file="string:This is my template, {$foo}!"} // 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 VARIABLE SCOPE / VARIABLE STORAGE
================================= =================================
In Smarty 2 all Smarty variables were stored within the Smarty object. In Smarty 2, all assigned variables were stored within the Smarty object.
So all variables assigned by the PHP script were accessible by all subsequent Therefore, all variables assigned in PHP were accessible by all subsequent
fetch and display template calls. fetch and display template calls.
In Smarty 3 we do have the possibility to assign variables to the Smarty object, 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. 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 These objects can be chained. The object at the end of a chain can access all
the end of such a chain can access all variables belonging to that template and variables belonging to that template and all variables within the parent objects.
all variables within the parent chain. The Smarty object can only be the root The Smarty object can only be the root of a chain, but a chain can be isolated
of such a chain, but a chain can also be isolated from the Smarty root. 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: A Smarty data object can be created as follows:
$data = new Smarty_Data; // create root data object not linked to any parent $data = new Smarty_Data; // create root data object
$data->assign(<EFBFBD>foo<EFBFBD>,<2C>bar<EFBFBD>); // assign variable $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
A template object can be created by using the createTemplate method. It has the same parameter as the fetch or display method. same parameter assignments as the fetch() or display() method.
Function definition:
function createTemplate($template, $cache_id = null, $compile_id = null, $parent = null) 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: Examples:
$tpl = $smarty->createTemplate(<EFBFBD>mytpl.tpl<EFBFBD>); // create template object not linked to any parent $tpl = $smarty->createTemplate('mytpl.tpl'); // create template object not linked to any parent
$tpl->assign(<EFBFBD>foo<EFBFBD>,<2C>bar<EFBFBD>); // assign variable $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 All variables assigned locally or from a parent template are accessible. If the
specified in these method calls for BC reasons the template object is linked back to the Smarty object as parent. 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 With Smarty 3, we can assign variables with a scope attribute which allows the
template as parent. availablility of these new variables or modifications globally (ie in the parent
templates.)
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. Possible scopes are local, parent, root and global.
Examples: Examples:
{assign var=foo value=<EFBFBD>bar<EFBFBD>} // no scope is specified, the default <EFBFBD>local<EFBFBD> will apply. Values can only be {assign var=foo value='bar'} // no scope is specified, the default 'local'
// seen in the current template {$foo='bar'} // same, local scope
{$foo=<3D>bar<61>} {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 {assign var=foo value='bar' scope='parent'} // Values will be available to the parent object
// (normally the calling template) {$foo='bar' scope='parent'} // (normally the calling template)
{$foo=<3D>bar<61> scope=parent}
{assign var=foo value=<EFBFBD>bar<EFBFBD> scope=root} // Values will be exported to the root object, so they can {assign var=foo value='bar' scope='root'} // Values will be exported up to the root object, so they can
// be seen from all templates using the same root. {$foo='bar' scope='root'} // be seen from all templates using the same root.
{$foo=<3D>bar<61> scope=root}
{assign var=foo value=<EFBFBD>bar<EFBFBD> scope=global} // Values will be exported to the global variable storage, {assign var=foo value='bar' scope='global'} // Values will be exported to global variable storage,
//so they can be seen from all templates. {$foo='bar' scope='global'} // they are available to any and 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 scope attribute can also be attached to the {include...} tag. In this case,
the default scope for all assignments within the included template. the specified scope will be the default scope for all assignments within the
included template.
PLUGINS 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. 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 PHP TEMPLATES
============= =============
@@ -370,14 +358,13 @@ In PHP templates, assigned vars are available simply as:
<?php echo $foo; ?> <?php echo $foo; ?>
<?=$foo?> // php short tags <?=$foo?> // php short tags
You can't use Smarty modifiers from the plugin folder. At this point, smarty modifier/function plugins are not
They must be implemented as PHP function. conveniently accessible from PHP templates. A wrapper
function may become available in the future.
You can call PHP functions a usual: You can call PHP functions a usual:
<?php echo foo($bar); ?> <?php echo foo($bar); ?>
Please look through it and send any questions/suggestions/etc to the forums. Please look through it and send any questions/suggestions/etc to the forums.
http://www.phpinsider.com/smarty-forum/viewtopic.php?t=14168 http://www.phpinsider.com/smarty-forum/viewtopic.php?t=14168