[Summary view] [Print] [Text view]

   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    Adressing 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;