library/smarty/SMARTY_3.1_NOTES.txt
changeset 0 4869aea77e21
equal deleted inserted replaced
-1:000000000000 0:4869aea77e21
       
     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;