library/Smarty/SMARTY_3.1_NOTES.txt

   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;