+
−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.
+
−
+
−  Addressing 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;