first commit
This commit is contained in:
291
lib/smarty/NEW_FEATURES.txt
Normal file
291
lib/smarty/NEW_FEATURES.txt
Normal file
@ -0,0 +1,291 @@
|
||||
|
||||
|
||||
This file contains a brief description of new features which have been added to Smarty 3.1
|
||||
|
||||
Smarty 3.1.33-dev
|
||||
Variable capture name in Smarty special variable
|
||||
================================================
|
||||
{$smarty.capture.$foo} can now be used to access the content of a named
|
||||
capture block
|
||||
|
||||
Smarty 3.1.32
|
||||
New tags for inheritance parent and child
|
||||
=========================================
|
||||
{parent} == {$smarty.block.parent}
|
||||
{child} == {$smarty.block.child}
|
||||
Both tags support the assign attribute like
|
||||
{child assign=foo}
|
||||
|
||||
Deprecate functions Smarty::muteExpectedErrors() and Smarty::unmuteExpectedErrors()
|
||||
===================================================================================
|
||||
These functions to start a special error handler are no longer needed as Smarty does
|
||||
no longer use error suppression like @filemtime().
|
||||
For backward compatibility the functions still can be called.
|
||||
|
||||
Using literals containing Smarty's left and right delimiter
|
||||
===========================================================
|
||||
New Methods
|
||||
$smarty->setLiterals(array $literals)
|
||||
$smarty->addLiterals(array $literals)
|
||||
to define literals containing Smarty delimiter. This can avoid the need for extreme usage
|
||||
of {literal} {/literal} tags.
|
||||
A) Treat '{{' and '}}' as literal
|
||||
If Smarty::$auto_literal is enabled
|
||||
{{ foo }}
|
||||
will be treated now as literal. (This does apply for any number of delimiter repeatations).
|
||||
However {{foo}} is not an literal but will be interpreted as a recursive Smarty tag.
|
||||
If you use
|
||||
$smarty->setLiterals(array('{{','}}'));
|
||||
{{foo}} is now a literal as well.
|
||||
NOTE: In the last example nested Smarty tags starting with '{{' or ending with '}}' will not
|
||||
work any longer, but this should be very very raw occouring restriction.
|
||||
B) Example 2
|
||||
Assume your delimiter are '<-' , '->' and '<--' , '-->' shall be literals
|
||||
$smarty->setLiterals(array('<--','-->'));
|
||||
|
||||
|
||||
The capture buffers can now be accessed as array
|
||||
================================================
|
||||
{capture name='foo'}
|
||||
bah
|
||||
{\capture}
|
||||
{capture name='buh'}
|
||||
blar
|
||||
{\capture}
|
||||
{foreach $smarty.capture as $name => $buffer}
|
||||
....
|
||||
{/foreach}
|
||||
|
||||
Smarty 3.1.31
|
||||
New tags for inheritance parent and child
|
||||
=========================================
|
||||
{block_parent} == {$smarty.block.parent}
|
||||
{block_child} == {$smarty.block.child}
|
||||
|
||||
Smarty 3.1.30
|
||||
|
||||
Loop optimization {foreach} and {section}
|
||||
=========================================
|
||||
Smarty does optimize the {foreach} and {section} loops by removing code for not needed loop
|
||||
properties.
|
||||
The compiler collects needed properties by scanning the current template for $item@property,
|
||||
$smarty.foreach.name.property and $smarty.section.name.property.
|
||||
The compiler does not know if additional properties will be needed outside the current template scope.
|
||||
Additional properties can be generated by adding them with the property attribute.
|
||||
|
||||
Example:
|
||||
index.tpl
|
||||
{foreach $from as $item properties=[iteration, index]}
|
||||
{include 'sub.tpl'}
|
||||
{$item.total}
|
||||
{/foreach}
|
||||
|
||||
sub.tpl
|
||||
{$item.index} {$item.iteration} {$item.total}
|
||||
|
||||
In above example code for the 'total' property is automatically generated as $item.total is used in
|
||||
index.tpl. Code for 'iteration' and 'index' must be added with properties=[iteration, index].
|
||||
|
||||
New tag {make_nocache}
|
||||
======================
|
||||
Syntax: {make_nocache $foo}
|
||||
|
||||
This tag makes a variable which does exists normally only while rendering the compiled template
|
||||
available in the cached template for use in not cached expressions.
|
||||
|
||||
Expample:
|
||||
{foreach from=$list item=item}
|
||||
<li>{$item.name} {make_nocache $item}{if $current==$item.id} ACTIVE{/if}</li>
|
||||
{/foreach}
|
||||
|
||||
The {foreach} loop is rendered while processing the compiled template, but $current is a nocache
|
||||
variable. Normally the {if $current==$item.id} would fail as the $item variable is unknown in the cached template. {make_nocache $item} does make the current $item value known in thee cached template.
|
||||
|
||||
{make_nocache} is ignored when caching is disabled or the variable does exists as nocache variable.
|
||||
|
||||
NOTE: if the variable value does contain objects these must have the __set_state method implemented.
|
||||
|
||||
|
||||
Scope Attributes
|
||||
================
|
||||
The scope handling has been updated to cover all cases of variable assignments in templates.
|
||||
|
||||
The tags {assign}, {append} direct assignments like {$foo = ...}, {$foo[...]= ...} support
|
||||
the following optional scope attributes:
|
||||
scope='parent' - the variable will be assigned in the current template and if the template
|
||||
was included by {include} the calling template
|
||||
scope='tpl_root' - the variable will be assigned in the outermost root template called by $smarty->display()
|
||||
or $smarty->fetch() and is bubbled up all {include} sub-templates to the current template.
|
||||
scope='smarty' - the variable will be assigned in the Smarty object and is bubbled up all {include} sub-templates
|
||||
to the current template.
|
||||
scope='global' - the variable will be assigned as Smarty object global variable and is bubbled up all {include}
|
||||
sub-templates to the current template.
|
||||
scope='root' - the variable will be assigned if a data object was used for variable definitions in the data
|
||||
object or in the Smarty object otherwise and is bubbled up all {include} sub-templates to the
|
||||
current template.
|
||||
scope='local' - this scope has only a meaning if the tag is called within a template {function}.
|
||||
The variable will be assigned in the local scope of the template function and the
|
||||
template which did call the template function.
|
||||
|
||||
|
||||
The {config_load} tag supports all of the above except the global scope.
|
||||
|
||||
The scope attribute can be used also with the {include} tag.
|
||||
Supported scope are parent, tpl_root, smarty, global and root.
|
||||
A scope used together with the {include} tag will cause that with some exceptions any variable
|
||||
assignment within that sub-template will update/assign the variable in other scopes according
|
||||
to the above rules. It does include also variables assigned by plugins, tags supporting the assign=foo attribute and direct assignments in {if} and {while} like {if $foo=$bar}.
|
||||
Excluded are the key and value variables of {foreach}, {for} loop variables , variables passed by attributes
|
||||
in {include} and direct increments/decrements like {$foo++}, {$foo--}
|
||||
|
||||
Note: The scopes should be used only to the extend really need. If a variable value assigned in an included
|
||||
sub-template should be returned to the calling sub-template just use {$foo='bar' scope='parent'}.
|
||||
Use scopes only with variables for which it's realy needed. Avoid general scope settings with the
|
||||
{include} tag as it can have a performance impact.
|
||||
|
||||
The {assign}, {append}, {config_load} and {$foo...=...} tags have a new option flag 'noscope'.Thi
|
||||
Example: {$foo='bar' noscope} This will assign $foo only in the current template and any scope settings
|
||||
at {include} is ignored.
|
||||
|
||||
|
||||
Caching
|
||||
=======
|
||||
Caching does now observe the template_dir setting and will create separate cache files if required
|
||||
|
||||
Compiled Templates
|
||||
==================
|
||||
The template_dir setting is now encoded in the uid of the file name.
|
||||
The content of the compiled template may depend on the template_dir search order
|
||||
{include .... inline} is used or $smarty->merge_compiled_includes is enabled
|
||||
|
||||
APC
|
||||
===
|
||||
If APC is enabled force an apc_compile_file() when compiled or cached template was updated
|
||||
|
||||
Smarty 3.1.28
|
||||
|
||||
OPCACHE
|
||||
=======
|
||||
Smarty does now invalidate automatically updated and cleared compiled or cached template files in OPCACHE.
|
||||
Correct operation is no longer dependent on OPCACHE configuration settings.
|
||||
|
||||
Template inheritance
|
||||
====================
|
||||
Template inheritance is now processed in run time.
|
||||
See the INHERITANCE_RELEASE_NOTES
|
||||
|
||||
Modifier regex_replace
|
||||
======================
|
||||
An optional limit parameter was added
|
||||
|
||||
fetch() and display()
|
||||
=====================
|
||||
The fetch() and display() methods of the template object accept now optionally the same parameter
|
||||
as the corresponding Smarty methods to get the content of another template.
|
||||
Example:
|
||||
$template->display(); Does display template of template object
|
||||
$template->display('foo.tpl'); Does display template 'foo.bar'
|
||||
|
||||
File: resource
|
||||
==============
|
||||
Multiple template_dir entries can now be selected by a comma separated list of indices.
|
||||
The template_dir array is searched in the order of the indices. (Could be used to change the default search order)
|
||||
Example:
|
||||
$smarty->display('[1],[0]foo.bar');
|
||||
|
||||
Filter support
|
||||
==============
|
||||
Optional filter names
|
||||
An optional filter name was added to $smarty->registerFilter(). It can be used to unregister a filter by name.
|
||||
- $smarty->registerFilter('output', $callback, 'name');
|
||||
$smarty->unregister('output', 'name');
|
||||
|
||||
Closures
|
||||
$smarty->registerFilter() does now accept closures.
|
||||
- $smarty->registerFilter('pre', function($source) {return $source;});
|
||||
If no optional filter name was specified it gets the default name 'closure'.
|
||||
If you register multiple closures register each with a unique filter name.
|
||||
- $smarty->registerFilter('pre', function($source) {return $source;}, 'closure_1');
|
||||
- $smarty->registerFilter('pre', function($source) {return $source;}, 'closure_2');
|
||||
|
||||
|
||||
Smarty 3.1.22
|
||||
|
||||
Namespace support within templates
|
||||
==================================
|
||||
Within templates you can now use namespace specifications on:
|
||||
- Constants like foo\bar\FOO
|
||||
- Class names like foo\bar\Baz::FOO, foo\bar\Baz::$foo, foo\bar\Baz::foo()
|
||||
- PHP function names like foo\bar\baz()
|
||||
|
||||
Security
|
||||
========
|
||||
- disable special $smarty variable -
|
||||
The Smarty_Security class has the new property $disabled_special_smarty_vars.
|
||||
It's an array which can be loaded with the $smarty special variable names like
|
||||
'template_object', 'template', 'current_dir' and others which will be disabled.
|
||||
Note: That this security check is performed at compile time.
|
||||
|
||||
- limit template nesting -
|
||||
Property $max_template_nesting of Smarty_Security does set the maximum template nesting level.
|
||||
The main template is level 1. The nesting level is checked at run time. When the maximum will be exceeded
|
||||
an Exception will be thrown. The default setting is 0 which does disable this check.
|
||||
|
||||
- trusted static methods -
|
||||
The Smarty_Security class has the new property $trusted_static_methods to restrict access to static methods.
|
||||
It's an nested array of trusted class and method names.
|
||||
Format:
|
||||
array (
|
||||
'class_1' => array('method_1', 'method_2'), // allowed methods
|
||||
'class_2' => array(), // all methods of class allowed
|
||||
)
|
||||
To disable access for all methods of all classes set $trusted_static_methods = null;
|
||||
The default value is an empty array() which does enables all methods of all classes, but for backward compatibility
|
||||
the setting of $static_classes will be checked.
|
||||
Note: That this security check is performed at compile time.
|
||||
|
||||
- trusted static properties -
|
||||
The Smarty_Security class has the new property $trusted_static_properties to restrict access to static properties.
|
||||
It's an nested array of trusted class and property names.
|
||||
Format:
|
||||
array (
|
||||
'class_1' => array('prop_1', 'prop_2'), // allowed properties listed
|
||||
'class_2' => array(), // all properties of class allowed
|
||||
}
|
||||
To disable access for all properties of all classes set $trusted_static_properties = null;
|
||||
The default value is an empty array() which does enables all properties of all classes, but for backward compatibility
|
||||
the setting of $static_classes will be checked.
|
||||
Note: That this security check is performed at compile time.
|
||||
|
||||
- trusted constants .
|
||||
The Smarty_Security class has the new property $trusted_constants to restrict access to constants.
|
||||
It's an array of trusted constant names.
|
||||
Format:
|
||||
array (
|
||||
'SMARTY_DIR' , // allowed constant
|
||||
}
|
||||
If the array is empty (default) the usage of constants can be controlled with the
|
||||
Smarty_Security::$allow_constants property (default true)
|
||||
|
||||
|
||||
|
||||
Compiled Templates
|
||||
==================
|
||||
Smarty does now automatically detects a change of the $merge_compiled_includes and $escape_html
|
||||
property and creates different compiled templates files depending on the setting.
|
||||
|
||||
Same applies to config files and the $config_overwrite, $config_booleanize and
|
||||
$config_read_hidden properties.
|
||||
|
||||
Debugging
|
||||
=========
|
||||
The layout of the debug window has been changed for better readability
|
||||
|
||||
New class constants
|
||||
Smarty::DEBUG_OFF
|
||||
Smarty::DEBUG_ON
|
||||
Smarty::DEBUG_INDIVIDUAL
|
||||
have been introduced for setting the $debugging property.
|
||||
|
||||
Smarty::DEBUG_INDIVIDUAL will create for each display() and fetch() call an individual debug window.
|
||||
|
Reference in New Issue
Block a user