diff --git a/README b/README index c5cf8b3a..2028addf 100644 --- a/README +++ b/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} {/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 “chained”. 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…. 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(‘foo’,’bar’); // 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(‘mytpl.tpl’); // create template object not linked to any parent -$tpl->assign(‘foo’,’bar’); // 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(‘mytpl.tpl’,$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(‘mytpl.tpl’,$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…} or {$foo=…} 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=’bar’} // no scope is specified, the default ‘local’ will apply. Values can only be - // seen in the current template -{$foo=’bar’} +{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 exported to the parent object - // (normally the calling template) -{$foo=’bar’ 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=’bar’ scope=root} // Values will be exported to the root object, so they can - // be seen from all templates using the same root. -{$foo=’bar’ 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=’bar’ scope=global} // Values will be exported to the global variable storage, - //so they can be seen from all templates. -{$foo=’bar’ 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 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: - - Please look through it and send any questions/suggestions/etc to the forums. http://www.phpinsider.com/smarty-forum/viewtopic.php?t=14168