source: trunk/include/smarty/SMARTY_3.1_NOTES.txt @ 27403

Smarty 3.1 Notes
================

Smarty 3.1 is a departure from 2.0 compatibility. Most notably, all
backward compatibility has been moved to a separate class file named
SmartyBC.class.php. If you require compatibility with 2.0, you will
need to use this class.

Some differences from 3.0 are also present. 3.1 begins the journey of
requiring setters/getters for property access. So far this is only
implemented on the five directory properties: template_dir,
plugins_dir, configs_dir, compile_dir and cache_dir. These properties
are now protected, it is required to use the setters/getters instead.
That said, direct property access will still work, however slightly
slower since they will now fall through __set() and __get() and in
turn passed through the setter/getter methods. 3.2 will exhibit a full
list of setter/getter methods for all (currently) public properties,
so code-completion in your IDE will work as expected.

There is absolutely no PHP allowed in templates any more. All
deprecated features of Smarty 2.0 are gone. Again, use the SmartyBC
class if you need any backward compatibility.

Internal Changes

  Full UTF-8 Compatibility

The plugins shipped with Smarty 3.1 have been rewritten to fully
support UTF-8 strings if Multibyte String is available. Without
MBString UTF-8 cannot be handled properly. For those rare cases where
templates themselves have to juggle encodings, the new modifiers
to_charset and from_charset may come in handy.

  Plugin API and Performance

All Plugins (modifiers, functions, blocks, resources,
default_template_handlers, etc) are now receiving the
Smarty_Internal_Template instance, where they were supplied with the
Smarty instance in Smarty 3.0. *. As The Smarty_Internal_Template
mimics the behavior of Smarty, this API simplification should not
require any changes to custom plugins.

The plugins shipped with Smarty 3.1 have been rewritten for better
performance. Most notably {html_select_date} and {html_select_time}
have been improved vastly. Performance aside, plugins have also been
reviewed and generalized in their API. {html_select_date} and
{html_select_time} now share almost all available options.

The escape modifier now knows the $double_encode option, which will
prevent entities from being encoded again.

The capitalize modifier now know the $lc_rest option, which makes sure
all letters following a captial letter are lower-cased.

The count_sentences modifier now accepts (.?!) as
legitimate endings of a sentence - previously only (.) was
accepted

The new unescape modifier is there to reverse the effects of the
escape modifier. This applies to the escape formats html, htmlall and
entity.

  default_template_handler_func

The invocation of $smarty->$default_template_handler_func had to be 
altered. Instead of a Smarty_Internal_Template, the fifth argument is
now provided with the Smarty instance. New footprint:


/**
 * Default Template Handler
 *
 * called when Smarty's file: resource is unable to load a requested file
 * 
 * @param string   $type     resource type (e.g. "file", "string", "eval", "resource")
 * @param string   $name     resource name (e.g. "foo/bar.tpl")
 * @param string  &$content  template's content
 * @param integer &$modified template's modification time
 * @param Smarty   $smarty   Smarty instance
 * @return string|boolean   path to file or boolean true if $content and $modified 
 *                          have been filled, boolean false if no default template 
 *                          could be loaded
 */
function default_template_handler_func($type, $name, &$content, &$modified, Smarty $smarty) {
    if (false) {
        // return corrected filepath
        return "/tmp/some/foobar.tpl";
    } elseif (false) {
        // return a template directly
        $content = "the template source";
        $modified = time();
        return true;
    } else {
        // tell smarty that we failed
        return false;
    }
}

  Stuff done to the compiler

Many performance improvements have happened internally. One notable
improvement is that all compiled templates are now handled as PHP
functions. This speeds up repeated templates tremendously, as each one
calls an (in-memory) PHP function instead of performing another file
include/scan.

New Features

  Template syntax

 {block}..{/block}

The {block} tag has a new hide option flag. It does suppress the block
content if no corresponding child block exists.
EXAMPLE:
parent.tpl
{block name=body hide} child content "{$smarty.block.child}" was
inserted {block}
In the above example the whole block will be suppressed if no child
block "body" is existing.

 {setfilter}..{/setfilter}

The new {setfilter} block tag allows the definition of filters which
run on variable output.
SYNTAX:
{setfilter filter1|filter2|filter3....}
Smarty3 will lookup up matching filters in the following search order:
1. varibale filter plugin in plugins_dir.
2. a valid modifier. A modifier specification will also accept
additional parameter like filter2:'foo'
3. a PHP function
{/setfilter} will turn previous filter setting off again.
{setfilter} tags can be nested.
EXAMPLE:
{setfilter filter1}
  {$foo}
  {setfilter filter2}
    {$bar}
  {/setfilter}
  {$buh}
{/setfilter}
{$blar}
In the above example filter1 will run on the output of $foo, filter2
on $bar, filter1 again on $buh and no filter on $blar.
NOTES:
- {$foo nofilter} will suppress the filters
- These filters will run in addition to filters defined by
registerFilter('variable',...), autoLoadFilter('variable',...) and
defined default modifier.
- {setfilter} will effect only the current template, not included
subtemplates.

  Resource API

Smarty 3.1 features a new approach to resource management. The
Smarty_Resource API allows simple, yet powerful integration of custom
resources for templates and configuration files. It offers simple
functions for loading data from a custom resource (e.g. database) as
well as define new template types adhering to the special
non-compiling (e,g, plain php) and non-compile-caching (e.g. eval:
resource type) resources.

See demo/plugins/resource.mysql.php for an example custom database
resource.

Note that old-fashioned registration of callbacks for resource
management has been deprecated but is still possible with SmartyBC.

  CacheResource API

In line with the Resource API, the CacheResource API offers a more
comfortable handling of output-cache data. With the
Smarty_CacheResource_Custom accessing databases is made simple. With
the introduction of Smarty_CacheResource_KeyValueStore the
implementation of resources like memcache or APC became a no-brainer;
simple hash-based storage systems are now supporting hierarchical
output-caches.

See demo/plugins/cacheresource.mysql.php for an example custom
database CacheResource.
See demo/plugins/cacheresource.memcache.php for an example custom
memcache CacheResource using the KeyValueStore helper.

Note that old-fashioned registration of $cache_handler is not possible
anymore. As the functionality had not been ported to Smarty 3.0.x
properly, it has been dropped from 3.1 completely.

Locking facilities have been implemented to avoid concurrent cache 
generation. Enable cache locking by setting 
$smarty->cache_locking = true;

  Relative Paths in Templates (File-Resource)

As of Smarty 3.1 {include file="../foo.tpl"} and {include
file="./foo.tpl"} will resolve relative to the template they're in.
Relative paths are available with {include file="..."} and
{extends file="..."}. As $smarty->fetch('../foo.tpl') and
$smarty->fetch('./foo.tpl') cannot be relative to a template, an
exception is thrown.

  Adressing a specific $template_dir

Smarty 3.1 introduces the $template_dir index notation.
$smarty->fetch('[foo]bar.tpl') and {include file="[foo]bar.tpl"}
require the template bar.tpl to be loaded from $template_dir['foo'];
Smarty::setTemplateDir() and Smarty::addTemplateDir() offer ways to
define indexes along with the actual directories.

  Mixing Resources in extends-Resource

Taking the php extends: template resource one step further, it is now
possible to mix resources within an extends: call like
$smarty->fetch("extends:file:foo.tpl|db:bar.tpl");

To make eval: and string: resources available to the inheritance
chain, eval:base64:TPL_STRING and eval:urlencode:TPL_STRING have been
introduced. Supplying the base64 or urlencode flags will trigger
decoding the TPL_STRING in with either base64_decode() or urldecode().

  extends-Resource in template inheritance

Template based inheritance may now inherit from php's extends:
resource like {extends file="extends:foo.tpl|db:bar.tpl"}.

  New Smarty property escape_html

$smarty->escape_html = true will autoescape all template variable
output by calling htmlspecialchars({$output}, ENT_QUOTES,
SMARTY_RESOURCE_CHAR_SET).
NOTE:
This is a compile time option. If you change the setting you must make
sure that the templates get recompiled.

  New option at Smarty property compile_check

The automatic recompilation of modified templates can now be
controlled by the following settings:
$smarty->compile_check = COMPILECHECK_OFF (false) - template files
will not be checked
$smarty->compile_check = COMPILECHECK_ON (true) - template files will
always be checked
$smarty->compile_check = COMPILECHECK_CACHEMISS - template files will
be checked if caching is enabled and there is no existing cache file
or it has expired

  Automatic recompilation on Smarty version change

Templates will now be automatically recompiled on Smarty version
changes to avoide incompatibillities in the compiled code. Compiled
template checked against the current setting of the SMARTY_VERSION
constant.

  default_config_handler_func()

Analogous to the default_template_handler_func()
default_config_handler_func() has been introduced.

  default_plugin_handler_func()

An optional default_plugin_handler_func() can be defined which gets called 
by the compiler on tags which can't be resolved internally or by plugins.
The default_plugin_handler() can map tags to plugins on the fly.

New getters/setters

The following setters/getters will be part of the official
documentation, and will be strongly recommended. Direct property
access will still work for the foreseeable future... it will be
transparently routed through the setters/getters, and consequently a
bit slower.

array|string getTemplateDir( [string $index] )
replaces $smarty->template_dir; and $smarty->template_dir[$index];
Smarty setTemplateDir( array|string $path )
replaces $smarty->template_dir = "foo"; and $smarty->template_dir =
array("foo", "bar");
Smarty addTemplateDir( array|string $path, [string $index])
replaces $smarty->template_dir[] = "bar"; and
$smarty->template_dir[$index] = "bar";

array|string getConfigDir( [string $index] )
replaces $smarty->config_dir; and $smarty->config_dir[$index];
Smarty setConfigDir( array|string $path )
replaces $smarty->config_dir = "foo"; and $smarty->config_dir =
array("foo", "bar");
Smarty addConfigDir( array|string $path, [string $index])
replaces $smarty->config_dir[] = "bar"; and
$smarty->config_dir[$index] = "bar";

array getPluginsDir()
replaces $smarty->plugins_dir;
Smarty setPluginsDir( array|string $path )
replaces $smarty->plugins_dir = "foo";
Smarty addPluginsDir( array|string $path )
replaces $smarty->plugins_dir[] = "bar";

string getCompileDir()
replaces $smarty->compile_dir;
Smarty setCompileDir( string $path )
replaces $smarty->compile_dir = "foo";

string getCacheDir()
replaces $smarty->cache_dir;
Smarty setCacheDir( string $path )
replaces $smarty->cache_dir;