Smarty 3.1 Notes================Smarty 3.1 is a departure from 2.0 compatibility. Most notably, allbackward compatibility has been moved to a separate class file namedSmartyBC.class.php. If you require compatibility with 2.0, you willneed to use this class.Some differences from 3.0 are also present. 3.1 begins the journey ofrequiring setters/getters for property access. So far this is onlyimplemented on the five directory properties: template_dir,plugins_dir, configs_dir, compile_dir and cache_dir. These propertiesare now protected, it is required to use the setters/getters instead.That said, direct property access will still work, however slightlyslower since they will now fall through __set() and __get() and inturn passed through the setter/getter methods. 3.2 will exhibit a fulllist 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. Alldeprecated features of Smarty 2.0 are gone. Again, use the SmartyBCclass if you need any backward compatibility.Internal Changes Full UTF-8 CompatibilityThe plugins shipped with Smarty 3.1 have been rewritten to fullysupport UTF-8 strings if Multibyte String is available. WithoutMBString UTF-8 cannot be handled properly. For those rare cases wheretemplates themselves have to juggle encodings, the new modifiersto_charset and from_charset may come in handy. Plugin API and PerformanceAll Plugins (modifiers, functions, blocks, resources,default_template_handlers, etc) are now receiving theSmarty_Internal_Template instance, where they were supplied with theSmarty instance in Smarty 3.0. *. As The Smarty_Internal_Templatemimics the behavior of Smarty, this API simplification should notrequire any changes to custom plugins.The plugins shipped with Smarty 3.1 have been rewritten for betterperformance. Most notably {html_select_date} and {html_select_time}have been improved vastly. Performance aside, plugins have also beenreviewed 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 willprevent entities from being encoded again.The capitalize modifier now know the $lc_rest option, which makes sureall letters following a captial letter are lower-cased.The count_sentences modifier now accepts (.?!) aslegitimate endings of a sentence - previously only (.) wasacceptedThe new unescape modifier is there to reverse the effects of theescape modifier. This applies to the escape formats html, htmlall andentity. default_template_handler_funcThe invocation of $smarty->$default_template_handler_func had to be altered. Instead of a Smarty_Internal_Template, the fifth argument isnow 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 compilerMany performance improvements have happened internally. One notableimprovement is that all compiled templates are now handled as PHPfunctions. This speeds up repeated templates tremendously, as each onecalls an (in-memory) PHP function instead of performing another fileinclude/scan.New Features Template syntax {block}..{/block}The {block} tag has a new hide option flag. It does suppress the blockcontent if no corresponding child block exists.EXAMPLE:parent.tpl{block name=body hide} child content "{$smarty.block.child}" wasinserted {block}In the above example the whole block will be suppressed if no childblock "body" is existing. {setfilter}..{/setfilter}The new {setfilter} block tag allows the definition of filters whichrun 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 acceptadditional 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, filter2on $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 byregisterFilter('variable',...), autoLoadFilter('variable',...) anddefined default modifier.- {setfilter} will effect only the current template, not includedsubtemplates. Resource APISmarty 3.1 features a new approach to resource management. TheSmarty_Resource API allows simple, yet powerful integration of customresources for templates and configuration files. It offers simplefunctions for loading data from a custom resource (e.g. database) aswell as define new template types adhering to the specialnon-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 databaseresource.Note that old-fashioned registration of callbacks for resourcemanagement has been deprecated but is still possible with SmartyBC. CacheResource APIIn line with the Resource API, the CacheResource API offers a morecomfortable handling of output-cache data. With theSmarty_CacheResource_Custom accessing databases is made simple. Withthe introduction of Smarty_CacheResource_KeyValueStore theimplementation of resources like memcache or APC became a no-brainer;simple hash-based storage systems are now supporting hierarchicaloutput-caches.See demo/plugins/cacheresource.mysql.php for an example customdatabase CacheResource.See demo/plugins/cacheresource.memcache.php for an example custommemcache CacheResource using the KeyValueStore helper.Note that old-fashioned registration of $cache_handler is not possibleanymore. As the functionality had not been ported to Smarty 3.0.xproperly, 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 {includefile="./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, anexception is thrown. Addressing a specific $template_dirSmarty 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 todefine indexes along with the actual directories. Mixing Resources in extends-ResourceTaking the php extends: template resource one step further, it is nowpossible 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 inheritancechain, eval:base64:TPL_STRING and eval:urlencode:TPL_STRING have beenintroduced. Supplying the base64 or urlencode flags will triggerdecoding the TPL_STRING in with either base64_decode() or urldecode(). extends-Resource in template inheritanceTemplate 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 variableoutput by calling htmlspecialchars({$output}, ENT_QUOTES,SMARTY_RESOURCE_CHAR_SET).NOTE:This is a compile time option. If you change the setting you must makesure that the templates get recompiled. New option at Smarty property compile_checkThe automatic recompilation of modified templates can now becontrolled by the following settings:$smarty->compile_check = COMPILECHECK_OFF (false) - template fileswill not be checked$smarty->compile_check = COMPILECHECK_ON (true) - template files willalways be checked$smarty->compile_check = COMPILECHECK_CACHEMISS - template files willbe checked if caching is enabled and there is no existing cache fileor it has expired Automatic recompilation on Smarty version changeTemplates will now be automatically recompiled on Smarty versionchanges to avoide incompatibillities in the compiled code. Compiledtemplate checked against the current setting of the SMARTY_VERSIONconstant. 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/settersThe following setters/getters will be part of the officialdocumentation, and will be strongly recommended. Direct propertyaccess will still work for the foreseeable future... it will betransparently routed through the setters/getters, and consequently abit 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;