1 Smarty 3.1 Notes

     2 ================

     3 

     4 Smarty 3.1 is a departure from 2.0 compatibility. Most notably, all

     5 backward compatibility has been moved to a separate class file named

     6 SmartyBC.class.php. If you require compatibility with 2.0, you will

     7 need to use this class.

     8 

     9 Some differences from 3.0 are also present. 3.1 begins the journey of

    10 requiring setters/getters for property access. So far this is only

    11 implemented on the five directory properties: template_dir,

    12 plugins_dir, configs_dir, compile_dir and cache_dir. These properties

    13 are now protected, it is required to use the setters/getters instead.

    14 That said, direct property access will still work, however slightly

    15 slower since they will now fall through __set() and __get() and in

    16 turn passed through the setter/getter methods. 3.2 will exhibit a full

    17 list of setter/getter methods for all (currently) public properties,

    18 so code-completion in your IDE will work as expected.

    19 

    20 There is absolutely no PHP allowed in templates any more. All

    21 deprecated features of Smarty 2.0 are gone. Again, use the SmartyBC

    22 class if you need any backward compatibility.

    23 

    24 Internal Changes

    25 

    26   Full UTF-8 Compatibility

    27 

    28 The plugins shipped with Smarty 3.1 have been rewritten to fully

    29 support UTF-8 strings if Multibyte String is available. Without

    30 MBString UTF-8 cannot be handled properly. For those rare cases where

    31 templates themselves have to juggle encodings, the new modifiers

    32 to_charset and from_charset may come in handy.

    33 

    34   Plugin API and Performance

    35 

    36 All Plugins (modifiers, functions, blocks, resources,

    37 default_template_handlers, etc) are now receiving the

    38 Smarty_Internal_Template instance, where they were supplied with the

    39 Smarty instance in Smarty 3.0. *. As The Smarty_Internal_Template

    40 mimics the behavior of Smarty, this API simplification should not

    41 require any changes to custom plugins.

    42 

    43 The plugins shipped with Smarty 3.1 have been rewritten for better

    44 performance. Most notably {html_select_date} and {html_select_time}

    45 have been improved vastly. Performance aside, plugins have also been

    46 reviewed and generalized in their API. {html_select_date} and

    47 {html_select_time} now share almost all available options.

    48 

    49 The escape modifier now knows the $double_encode option, which will

    50 prevent entities from being encoded again.

    51 

    52 The capitalize modifier now know the $lc_rest option, which makes sure

    53 all letters following a captial letter are lower-cased.

    54 

    55 The count_sentences modifier now accepts (.?!) as

    56 legitimate endings of a sentence - previously only (.) was

    57 accepted

    58 

    59 The new unescape modifier is there to reverse the effects of the

    60 escape modifier. This applies to the escape formats html, htmlall and

    61 entity.

    62 

    63   default_template_handler_func

    64 

    65 The invocation of $smarty->$default_template_handler_func had to be 

    66 altered. Instead of a Smarty_Internal_Template, the fifth argument is

    67 now provided with the Smarty instance. New footprint:

    68 

    69 

    70 /**

    71  * Default Template Handler

    72  *

    73  * called when Smarty's file: resource is unable to load a requested file

    74  * 

    75  * @param string   $type     resource type (e.g. "file", "string", "eval", "resource")

    76  * @param string   $name     resource name (e.g. "foo/bar.tpl")

    77  * @param string  &$content  template's content

    78  * @param integer &$modified template's modification time

    79  * @param Smarty   $smarty   Smarty instance

    80  * @return string|boolean   path to file or boolean true if $content and $modified 

    81  *                          have been filled, boolean false if no default template 

    82  *                          could be loaded

    83  */

    84 function default_template_handler_func($type, $name, &$content, &$modified, Smarty $smarty) {

    85     if (false) {

    86         // return corrected filepath

    87         return "/tmp/some/foobar.tpl";

    88     } elseif (false) {

    89         // return a template directly

    90         $content = "the template source";

    91         $modified = time();

    92         return true;

    93     } else {

    94         // tell smarty that we failed

    95         return false;

    96     }

    97 }

    98 

    99   Stuff done to the compiler

   100 

   101 Many performance improvements have happened internally. One notable

   102 improvement is that all compiled templates are now handled as PHP

   103 functions. This speeds up repeated templates tremendously, as each one

   104 calls an (in-memory) PHP function instead of performing another file

   105 include/scan.

   106 

   107 New Features

   108 

   109   Template syntax

   110 

   111  {block}..{/block}

   112 

   113 The {block} tag has a new hide option flag. It does suppress the block

   114 content if no corresponding child block exists.

   115 EXAMPLE:

   116 parent.tpl

   117 {block name=body hide} child content "{$smarty.block.child}" was

   118 inserted {block}

   119 In the above example the whole block will be suppressed if no child

   120 block "body" is existing.

   121 

   122  {setfilter}..{/setfilter}

   123 

   124 The new {setfilter} block tag allows the definition of filters which

   125 run on variable output.

   126 SYNTAX:

   127 {setfilter filter1|filter2|filter3....}

   128 Smarty3 will lookup up matching filters in the following search order:

   129 1. varibale filter plugin in plugins_dir.

   130 2. a valid modifier. A modifier specification will also accept

   131 additional parameter like filter2:'foo'

   132 3. a PHP function

   133 {/setfilter} will turn previous filter setting off again.

   134 {setfilter} tags can be nested.

   135 EXAMPLE:

   136 {setfilter filter1}

   137   {$foo}

   138   {setfilter filter2}

   139     {$bar}

   140   {/setfilter}

   141   {$buh}

   142 {/setfilter}

   143 {$blar}

   144 In the above example filter1 will run on the output of $foo, filter2

   145 on $bar, filter1 again on $buh and no filter on $blar.

   146 NOTES:

   147 - {$foo nofilter} will suppress the filters

   148 - These filters will run in addition to filters defined by

   149 registerFilter('variable',...), autoLoadFilter('variable',...) and

   150 defined default modifier.

   151 - {setfilter} will effect only the current template, not included

   152 subtemplates.

   153 

   154   Resource API

   155 

   156 Smarty 3.1 features a new approach to resource management. The

   157 Smarty_Resource API allows simple, yet powerful integration of custom

   158 resources for templates and configuration files. It offers simple

   159 functions for loading data from a custom resource (e.g. database) as

   160 well as define new template types adhering to the special

   161 non-compiling (e,g, plain php) and non-compile-caching (e.g. eval:

   162 resource type) resources.

   163 

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

   165 resource.

   166 

   167 Note that old-fashioned registration of callbacks for resource

   168 management has been deprecated but is still possible with SmartyBC.

   169 

   170   CacheResource API

   171 

   172 In line with the Resource API, the CacheResource API offers a more

   173 comfortable handling of output-cache data. With the

   174 Smarty_CacheResource_Custom accessing databases is made simple. With

   175 the introduction of Smarty_CacheResource_KeyValueStore the

   176 implementation of resources like memcache or APC became a no-brainer;

   177 simple hash-based storage systems are now supporting hierarchical

   178 output-caches.

   179 

   180 See demo/plugins/cacheresource.mysql.php for an example custom

   181 database CacheResource.

   182 See demo/plugins/cacheresource.memcache.php for an example custom

   183 memcache CacheResource using the KeyValueStore helper.

   184 

   185 Note that old-fashioned registration of $cache_handler is not possible

   186 anymore. As the functionality had not been ported to Smarty 3.0.x

   187 properly, it has been dropped from 3.1 completely.

   188 

   189 Locking facilities have been implemented to avoid concurrent cache 

   190 generation. Enable cache locking by setting 

   191 $smarty->cache_locking = true;

   192 

   193   Relative Paths in Templates (File-Resource)

   194 

   195 As of Smarty 3.1 {include file="../foo.tpl"} and {include

   196 file="./foo.tpl"} will resolve relative to the template they're in.

   197 Relative paths are available with {include file="..."} and

   198 {extends file="..."}. As $smarty->fetch('../foo.tpl') and

   199 $smarty->fetch('./foo.tpl') cannot be relative to a template, an

   200 exception is thrown.

   201 

   202   Addressing a specific $template_dir

   203 

   204 Smarty 3.1 introduces the $template_dir index notation.

   205 $smarty->fetch('[foo]bar.tpl') and {include file="[foo]bar.tpl"}

   206 require the template bar.tpl to be loaded from $template_dir['foo'];

   207 Smarty::setTemplateDir() and Smarty::addTemplateDir() offer ways to

   208 define indexes along with the actual directories.

   209 

   210   Mixing Resources in extends-Resource

   211 

   212 Taking the php extends: template resource one step further, it is now

   213 possible to mix resources within an extends: call like

   214 $smarty->fetch("extends:file:foo.tpl|db:bar.tpl");

   215 

   216 To make eval: and string: resources available to the inheritance

   217 chain, eval:base64:TPL_STRING and eval:urlencode:TPL_STRING have been

   218 introduced. Supplying the base64 or urlencode flags will trigger

   219 decoding the TPL_STRING in with either base64_decode() or urldecode().

   220 

   221   extends-Resource in template inheritance

   222 

   223 Template based inheritance may now inherit from php's extends:

   224 resource like {extends file="extends:foo.tpl|db:bar.tpl"}.

   225 

   226   New Smarty property escape_html

   227 

   228 $smarty->escape_html = true will autoescape all template variable

   229 output by calling htmlspecialchars({$output}, ENT_QUOTES,

   230 SMARTY_RESOURCE_CHAR_SET).

   231 NOTE:

   232 This is a compile time option. If you change the setting you must make

   233 sure that the templates get recompiled.

   234 

   235   New option at Smarty property compile_check

   236 

   237 The automatic recompilation of modified templates can now be

   238 controlled by the following settings:

   239 $smarty->compile_check = COMPILECHECK_OFF (false) - template files

   240 will not be checked

   241 $smarty->compile_check = COMPILECHECK_ON (true) - template files will

   242 always be checked

   243 $smarty->compile_check = COMPILECHECK_CACHEMISS - template files will

   244 be checked if caching is enabled and there is no existing cache file

   245 or it has expired

   246 

   247   Automatic recompilation on Smarty version change

   248 

   249 Templates will now be automatically recompiled on Smarty version

   250 changes to avoide incompatibillities in the compiled code. Compiled

   251 template checked against the current setting of the SMARTY_VERSION

   252 constant.

   253 

   254   default_config_handler_func()

   255 

   256 Analogous to the default_template_handler_func()

   257 default_config_handler_func() has been introduced.

   258 

   259   default_plugin_handler_func()

   260 

   261 An optional default_plugin_handler_func() can be defined which gets called 

   262 by the compiler on tags which can't be resolved internally or by plugins.

   263 The default_plugin_handler() can map tags to plugins on the fly.

   264 

   265 New getters/setters

   266 

   267 The following setters/getters will be part of the official

   268 documentation, and will be strongly recommended. Direct property

   269 access will still work for the foreseeable future... it will be

   270 transparently routed through the setters/getters, and consequently a

   271 bit slower.

   272 

   273 array|string getTemplateDir( [string $index] )

   274 replaces $smarty->template_dir; and $smarty->template_dir[$index];

   275 Smarty setTemplateDir( array|string $path )

   276 replaces $smarty->template_dir = "foo"; and $smarty->template_dir =

   277 array("foo", "bar");

   278 Smarty addTemplateDir( array|string $path, [string $index])

   279 replaces $smarty->template_dir[] = "bar"; and

   280 $smarty->template_dir[$index] = "bar";

   281 

   282 array|string getConfigDir( [string $index] )

   283 replaces $smarty->config_dir; and $smarty->config_dir[$index];

   284 Smarty setConfigDir( array|string $path )

   285 replaces $smarty->config_dir = "foo"; and $smarty->config_dir =

   286 array("foo", "bar");

   287 Smarty addConfigDir( array|string $path, [string $index])

   288 replaces $smarty->config_dir[] = "bar"; and

   289 $smarty->config_dir[$index] = "bar";

   290 

   291 array getPluginsDir()

   292 replaces $smarty->plugins_dir;

   293 Smarty setPluginsDir( array|string $path )

   294 replaces $smarty->plugins_dir = "foo";

   295 Smarty addPluginsDir( array|string $path )

   296 replaces $smarty->plugins_dir[] = "bar";

   297 

   298 string getCompileDir()

   299 replaces $smarty->compile_dir;

   300 Smarty setCompileDir( string $path )

   301 replaces $smarty->compile_dir = "foo";

   302 

   303 string getCacheDir()

   304 replaces $smarty->cache_dir;

   305 Smarty setCacheDir( string $path )

   306 replaces $smarty->cache_dir;