NEW_FEATURES.txt

This file contains a brief description of new features which have been added to Smarty 3.1

Smarty 3.1.32

    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->setLiteral(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->setLiteral(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.