vendor/smarty/smarty/NEW_FEATURES.txt

   1
   2
   3 This file contains a brief description of new features which have been added to Smarty 3.1
   4
   5 Smarty 3.1.31
   6     New tags for inheritance parent and child
   7     =========================================
   8     {block_parent}  == {$smarty.block.parent}
   9     {block_child}  == {$smarty.block.child}
  10
  11 Smarty 3.1.30
  12
  13     Loop optimization {foreach} and {section}
  14     =========================================
  15     Smarty does optimize the {foreach} and {section} loops by removing code for not needed loop
  16     properties.
  17     The compiler collects needed properties by scanning the current template for $item@property,
  18     $smarty.foreach.name.property and $smarty.section.name.property.
  19     The compiler does not know if additional properties will be needed outside the current template scope.
  20     Additional properties can be generated by adding them with the property attribute.
  21
  22     Example:
  23         index.tpl
  24         {foreach $from as $item properties=[iteration, index]}
  25             {include 'sub.tpl'}
  26             {$item.total}
  27         {/foreach}
  28
  29         sub.tpl
  30         {$item.index} {$item.iteration} {$item.total}
  31
  32     In above example code for the 'total' property is automatically generated as $item.total is used in
  33     index.tpl. Code for 'iteration' and 'index' must be added with properties=[iteration, index].
  34
  35     New tag {make_nocache}
  36     ======================
  37     Syntax: {make_nocache $foo}
  38
  39     This tag makes a variable which does exists normally only while rendering the compiled template
  40     available in the cached template for use in not cached expressions.
  41
  42     Expample:
  43         {foreach from=$list item=item}
  44             <li>{$item.name} {make_nocache $item}{if $current==$item.id} ACTIVE{/if}</li>
  45         {/foreach}
  46
  47     The {foreach} loop is rendered while processing the compiled template, but $current is a nocache
  48     variable. Normally the {if $current==$item.id} would fail as the $item variable is unkown in the
  49     cached template. {make_nocache $item} does make the current $item value known in thee cached template.
  50
  51     {make_nocache} is ignored when caching is disabled or the variable does exists as nocache variable.
  52
  53     NOTE: if the variable value does contain objects these must have the __set_state method implemented.
  54
  55
  56     Scope Attributes
  57     ================
  58     The scope handling has been updated to cover all cases of variable assignments in templates.
  59
  60     The tags {assign}, {append} direct assignments like {$foo = ...}, {$foo[...]= ...} support
  61     the following optional scope attributes:
  62     scope='parent'    - the variable will be assigned in the current template and if the template
  63                         was included by {include} the calling template
  64     scope='tpl_root'  - the variable will be assigned in the outermost root template called by $smarty->display()
  65                         or $smarty->fetch() and is bubbled up all {include} sub-templates to the current template.
  66     scope='smarty'    - the variable will be assigned in the Smarty object and is bubbled up all {include} sub-templates
  67                         to the current template.
  68     scope='global'    - the variable will be assigned as Smarty object global variable and is bubbled up all {include}
  69                         sub-templates to the current template.
  70     scope='root'      - the variable will be assigned if a data object was used for variable definitions in the data
  71                         object or in the Smarty object otherwise and is bubbled up all {include} sub-templates to the
  72                         current template.
  73     scope='local'     - this scope has only a meaning if the tag is called within a template {function}.
  74                         The variable will be assigned in the local scope of the template function and the
  75                         template which did call the template function.
  76
  77
  78     The {config_load} tag supports all of the above except the global scope.
  79
  80     The scope attribute can be used also with the {include} tag.
  81     Supported scope are parent, tpl_root, smarty, global and root.
  82     A scope used together with the {include} tag will cause that with some exceptions any variable
  83     assignment within that sub-template will update/assign the variable in other scopes according
  84     to the above rules. It does include also variables assigned by plugins, tags supporting the assign=foo
  85     attribute and direct assignments in {if} and {while} like {if $foo=$bar}.
  86     Excluded are the key and value variables of {foreach}, {for} loop variables , variables passed by attributes
  87     in {include} and direct increments/decrements like {$foo++}, {$foo--}
  88
  89     Note: The scopes should be used only to the extend really need. If a variable value assigned in an included
  90           sub-template should be returned to the calling sub-template just use {$foo='bar' scope='parent'}.
  91           Use scopes only with variables for which it's realy needed. Avoid general scope settings with the
  92           {include} tag as it can have a performance impact.
  93
  94      The {assign}, {append}, {config_load} and {$foo...=...} tags have a new option flag 'noscope'.Thi
  95      Example: {$foo='bar' noscope}  This will assign $foo only in the current template and any scope settings
  96                at {include} is ignored.
  97
  98
  99     Caching
 100     =======
 101     Caching does now observe the template_dir setting and will create separate cache files if required
 102
 103     Compiled Templates
 104     ==================
 105     The template_dir setting is now encoded in the uid of the file name.
 106     The content of the compiled template may depend on the template_dir search order
 107     {include .... inline} is used or $smarty->merge_compiled_includes is enabled
 108
 109     APC
 110     ===
 111     If APC is enabled force an apc_compile_file() when compiled or cached template was updated
 112
 113 Smarty 3.1.28
 114
 115     OPCACHE
 116     =======
 117     Smarty does now invalidate automatically updated and cleared compiled or cached template files in OPCACHE.
 118     Correct operation is no longer dependent on OPCACHE configuration settings.
 119
 120     Template inheritance
 121     ====================
 122     Template inheritance is now processed in run time.
 123     See the INHERITANCE_RELEASE_NOTES
 124
 125     Modifier regex_replace
 126     ======================
 127     An optional limit parameter was added
 128
 129     fetch() and display()
 130     =====================
 131     The fetch() and display() methods of the template object accept now optionally the same parameter
 132     as the corresponding Smarty methods to get the content of another template.
 133     Example:
 134         $template->display();           Does display template of template object
 135         $template->display('foo.tpl');  Does display template 'foo.bar'
 136
 137     File: resource
 138     ==============
 139     Multiple template_dir entries can now be selected  by a comma separated list of indices.
 140     The template_dir array is searched in the order of the indices. (Could be used to change the default search order)
 141     Example:
 142         $smarty->display('[1],[0]foo.bar');
 143
 144     Filter support
 145     ==============
 146     Optional filter names
 147       An optional filter name was added to $smarty->registerFilter(). It can be used to unregister a filter by name.
 148       - $smarty->registerFilter('output', $callback, 'name');
 149         $smarty->unregister('output', 'name');
 150
 151     Closures
 152       $smarty->registerFilter() does now accept closures.
 153       - $smarty->registerFilter('pre', function($source) {return $source;});
 154       If no optional filter name was specified it gets the default name 'closure'.
 155       If you register multiple closures register each with a unique filter name.
 156       - $smarty->registerFilter('pre', function($source) {return $source;}, 'closure_1');
 157       - $smarty->registerFilter('pre', function($source) {return $source;}, 'closure_2');
 158
 159
 160 Smarty 3.1.22
 161
 162     Namespace support within templates
 163     ==================================
 164     Within templates you can now use namespace specifications on:
 165      - Constants                like    foo\bar\FOO
 166      - Class names              like    foo\bar\Baz::FOO, foo\bar\Baz::$foo, foo\bar\Baz::foo()
 167      - PHP function names       like    foo\bar\baz()
 168
 169     Security
 170     ========
 171     - disable special $smarty variable -
 172     The Smarty_Security class has the new property $disabled_special_smarty_vars.
 173     It's an array which can be loaded with the $smarty special variable names like
 174     'template_object', 'template', 'current_dir' and others which will be disabled.
 175     Note: That this security check is performed at compile time.
 176
 177     - limit template nesting -
 178     Property $max_template_nesting of Smarty_Security does set the maximum template nesting level.
 179     The main template is level 1. The nesting level is checked at run time. When the maximum will be exceeded
 180     an Exception will be thrown. The default setting is 0 which does disable this check.
 181
 182     - trusted static methods -
 183    The Smarty_Security class has the new property $trusted_static_methods to restrict access to static methods.
 184    It's an nested array of trusted class and method names.
 185          Format:
 186          array (
 187                     'class_1' => array('method_1', 'method_2'), // allowed methods
 188                     'class_2' => array(),                       // all methods of class allowed
 189                )
 190    To disable access for all methods of all classes set $trusted_static_methods = null;
 191    The default value is an empty array() which does enables all methods of all classes, but for backward compatibility
 192    the setting of $static_classes will be checked.
 193    Note: That this security check is performed at compile time.
 194
 195     - trusted static properties -
 196    The Smarty_Security class has the new property $trusted_static_properties to restrict access to static properties.
 197    It's an nested array of trusted class and property names.
 198          Format:
 199          array (
 200                     'class_1' => array('prop_1', 'prop_2'), // allowed properties listed
 201                     'class_2' => array(),                   // all properties of class allowed
 202                 }
 203    To disable access for all properties of all classes set $trusted_static_properties = null;
 204    The default value is an empty array() which does enables all properties of all classes, but for backward compatibility
 205    the setting of $static_classes will be checked.
 206    Note: That this security check is performed at compile time.
 207
 208     - trusted constants .
 209    The Smarty_Security class has the new property $trusted_constants to restrict access to constants.
 210    It's an array of trusted constant names.
 211          Format:
 212          array (
 213                     'SMARTY_DIR' , // allowed constant
 214                 }
 215    If the array is empty (default) the usage of constants  can be controlled with the
 216    Smarty_Security::$allow_constants property (default true)
 217
 218
 219
 220     Compiled Templates
 221     ==================
 222     Smarty does now automatically detects a change of the $merge_compiled_includes and $escape_html
 223     property and creates different compiled templates files depending on the setting.
 224
 225     Same applies to config files and the $config_overwrite, $config_booleanize and
 226     $config_read_hidden properties.
 227
 228     Debugging
 229     =========
 230     The layout of the debug window has been changed for better readability
 231
 232     New class constants
 233         Smarty::DEBUG_OFF
 234         Smarty::DEBUG_ON
 235         Smarty::DEBUG_INDIVIDUAL
 236     have been introduced for setting the $debugging property.
 237
 238     Smarty::DEBUG_INDIVIDUAL will create for each display() and fetch() call an individual debug window.
 239