Friendica Communications Platform (please note that this is a clone of the repository at github, issues are handled there)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

306 lines
11 KiB

  1. Smarty 3.1 Notes
  2. ================
  3. Smarty 3.1 is a departure from 2.0 compatibility. Most notably, all
  4. backward compatibility has been moved to a separate class file named
  5. SmartyBC.class.php. If you require compatibility with 2.0, you will
  6. need to use this class.
  7. Some differences from 3.0 are also present. 3.1 begins the journey of
  8. requiring setters/getters for property access. So far this is only
  9. implemented on the five directory properties: template_dir,
  10. plugins_dir, configs_dir, compile_dir and cache_dir. These properties
  11. are now protected, it is required to use the setters/getters instead.
  12. That said, direct property access will still work, however slightly
  13. slower since they will now fall through __set() and __get() and in
  14. turn passed through the setter/getter methods. 3.2 will exhibit a full
  15. list of setter/getter methods for all (currently) public properties,
  16. so code-completion in your IDE will work as expected.
  17. There is absolutely no PHP allowed in templates any more. All
  18. deprecated features of Smarty 2.0 are gone. Again, use the SmartyBC
  19. class if you need any backward compatibility.
  20. Internal Changes
  21. Full UTF-8 Compatibility
  22. The plugins shipped with Smarty 3.1 have been rewritten to fully
  23. support UTF-8 strings if Multibyte String is available. Without
  24. MBString UTF-8 cannot be handled properly. For those rare cases where
  25. templates themselves have to juggle encodings, the new modifiers
  26. to_charset and from_charset may come in handy.
  27. Plugin API and Performance
  28. All Plugins (modifiers, functions, blocks, resources,
  29. default_template_handlers, etc) are now receiving the
  30. Smarty_Internal_Template instance, where they were supplied with the
  31. Smarty instance in Smarty 3.0. *. As The Smarty_Internal_Template
  32. mimics the behavior of Smarty, this API simplification should not
  33. require any changes to custom plugins.
  34. The plugins shipped with Smarty 3.1 have been rewritten for better
  35. performance. Most notably {html_select_date} and {html_select_time}
  36. have been improved vastly. Performance aside, plugins have also been
  37. reviewed and generalized in their API. {html_select_date} and
  38. {html_select_time} now share almost all available options.
  39. The escape modifier now knows the $double_encode option, which will
  40. prevent entities from being encoded again.
  41. The capitalize modifier now know the $lc_rest option, which makes sure
  42. all letters following a captial letter are lower-cased.
  43. The count_sentences modifier now accepts (.?!) as
  44. legitimate endings of a sentence - previously only (.) was
  45. accepted
  46. The new unescape modifier is there to reverse the effects of the
  47. escape modifier. This applies to the escape formats html, htmlall and
  48. entity.
  49. default_template_handler_func
  50. The invocation of $smarty->$default_template_handler_func had to be
  51. altered. Instead of a Smarty_Internal_Template, the fifth argument is
  52. now provided with the Smarty instance. New footprint:
  53. /**
  54. * Default Template Handler
  55. *
  56. * called when Smarty's file: resource is unable to load a requested file
  57. *
  58. * @param string $type resource type (e.g. "file", "string", "eval", "resource")
  59. * @param string $name resource name (e.g. "foo/bar.tpl")
  60. * @param string &$content template's content
  61. * @param integer &$modified template's modification time
  62. * @param Smarty $smarty Smarty instance
  63. * @return string|boolean path to file or boolean true if $content and $modified
  64. * have been filled, boolean false if no default template
  65. * could be loaded
  66. */
  67. function default_template_handler_func($type, $name, &$content, &$modified, Smarty $smarty) {
  68. if (false) {
  69. // return corrected filepath
  70. return "/tmp/some/foobar.tpl";
  71. } elseif (false) {
  72. // return a template directly
  73. $content = "the template source";
  74. $modified = time();
  75. return true;
  76. } else {
  77. // tell smarty that we failed
  78. return false;
  79. }
  80. }
  81. Stuff done to the compiler
  82. Many performance improvements have happened internally. One notable
  83. improvement is that all compiled templates are now handled as PHP
  84. functions. This speeds up repeated templates tremendously, as each one
  85. calls an (in-memory) PHP function instead of performing another file
  86. include/scan.
  87. New Features
  88. Template syntax
  89. {block}..{/block}
  90. The {block} tag has a new hide option flag. It does suppress the block
  91. content if no corresponding child block exists.
  92. EXAMPLE:
  93. parent.tpl
  94. {block name=body hide} child content "{$smarty.block.child}" was
  95. inserted {block}
  96. In the above example the whole block will be suppressed if no child
  97. block "body" is existing.
  98. {setfilter}..{/setfilter}
  99. The new {setfilter} block tag allows the definition of filters which
  100. run on variable output.
  101. SYNTAX:
  102. {setfilter filter1|filter2|filter3....}
  103. Smarty3 will lookup up matching filters in the following search order:
  104. 1. varibale filter plugin in plugins_dir.
  105. 2. a valid modifier. A modifier specification will also accept
  106. additional parameter like filter2:'foo'
  107. 3. a PHP function
  108. {/setfilter} will turn previous filter setting off again.
  109. {setfilter} tags can be nested.
  110. EXAMPLE:
  111. {setfilter filter1}
  112. {$foo}
  113. {setfilter filter2}
  114. {$bar}
  115. {/setfilter}
  116. {$buh}
  117. {/setfilter}
  118. {$blar}
  119. In the above example filter1 will run on the output of $foo, filter2
  120. on $bar, filter1 again on $buh and no filter on $blar.
  121. NOTES:
  122. - {$foo nofilter} will suppress the filters
  123. - These filters will run in addition to filters defined by
  124. registerFilter('variable',...), autoLoadFilter('variable',...) and
  125. defined default modifier.
  126. - {setfilter} will effect only the current template, not included
  127. subtemplates.
  128. Resource API
  129. Smarty 3.1 features a new approach to resource management. The
  130. Smarty_Resource API allows simple, yet powerful integration of custom
  131. resources for templates and configuration files. It offers simple
  132. functions for loading data from a custom resource (e.g. database) as
  133. well as define new template types adhering to the special
  134. non-compiling (e,g, plain php) and non-compile-caching (e.g. eval:
  135. resource type) resources.
  136. See demo/plugins/resource.mysql.php for an example custom database
  137. resource.
  138. Note that old-fashioned registration of callbacks for resource
  139. management has been deprecated but is still possible with SmartyBC.
  140. CacheResource API
  141. In line with the Resource API, the CacheResource API offers a more
  142. comfortable handling of output-cache data. With the
  143. Smarty_CacheResource_Custom accessing databases is made simple. With
  144. the introduction of Smarty_CacheResource_KeyValueStore the
  145. implementation of resources like memcache or APC became a no-brainer;
  146. simple hash-based storage systems are now supporting hierarchical
  147. output-caches.
  148. See demo/plugins/cacheresource.mysql.php for an example custom
  149. database CacheResource.
  150. See demo/plugins/cacheresource.memcache.php for an example custom
  151. memcache CacheResource using the KeyValueStore helper.
  152. Note that old-fashioned registration of $cache_handler is not possible
  153. anymore. As the functionality had not been ported to Smarty 3.0.x
  154. properly, it has been dropped from 3.1 completely.
  155. Locking facilities have been implemented to avoid concurrent cache
  156. generation. Enable cache locking by setting
  157. $smarty->cache_locking = true;
  158. Relative Paths in Templates (File-Resource)
  159. As of Smarty 3.1 {include file="../foo.tpl"} and {include
  160. file="./foo.tpl"} will resolve relative to the template they're in.
  161. Relative paths are available with {include file="..."} and
  162. {extends file="..."}. As $smarty->fetch('../foo.tpl') and
  163. $smarty->fetch('./foo.tpl') cannot be relative to a template, an
  164. exception is thrown.
  165. Addressing a specific $template_dir
  166. Smarty 3.1 introduces the $template_dir index notation.
  167. $smarty->fetch('[foo]bar.tpl') and {include file="[foo]bar.tpl"}
  168. require the template bar.tpl to be loaded from $template_dir['foo'];
  169. Smarty::setTemplateDir() and Smarty::addTemplateDir() offer ways to
  170. define indexes along with the actual directories.
  171. Mixing Resources in extends-Resource
  172. Taking the php extends: template resource one step further, it is now
  173. possible to mix resources within an extends: call like
  174. $smarty->fetch("extends:file:foo.tpl|db:bar.tpl");
  175. To make eval: and string: resources available to the inheritance
  176. chain, eval:base64:TPL_STRING and eval:urlencode:TPL_STRING have been
  177. introduced. Supplying the base64 or urlencode flags will trigger
  178. decoding the TPL_STRING in with either base64_decode() or urldecode().
  179. extends-Resource in template inheritance
  180. Template based inheritance may now inherit from php's extends:
  181. resource like {extends file="extends:foo.tpl|db:bar.tpl"}.
  182. New Smarty property escape_html
  183. $smarty->escape_html = true will autoescape all template variable
  184. output by calling htmlspecialchars({$output}, ENT_QUOTES,
  186. NOTE:
  187. This is a compile time option. If you change the setting you must make
  188. sure that the templates get recompiled.
  189. New option at Smarty property compile_check
  190. The automatic recompilation of modified templates can now be
  191. controlled by the following settings:
  192. $smarty->compile_check = COMPILECHECK_OFF (false) - template files
  193. will not be checked
  194. $smarty->compile_check = COMPILECHECK_ON (true) - template files will
  195. always be checked
  196. $smarty->compile_check = COMPILECHECK_CACHEMISS - template files will
  197. be checked if caching is enabled and there is no existing cache file
  198. or it has expired
  199. Automatic recompilation on Smarty version change
  200. Templates will now be automatically recompiled on Smarty version
  201. changes to avoide incompatibillities in the compiled code. Compiled
  202. template checked against the current setting of the SMARTY_VERSION
  203. constant.
  204. default_config_handler_func()
  205. Analogous to the default_template_handler_func()
  206. default_config_handler_func() has been introduced.
  207. default_plugin_handler_func()
  208. An optional default_plugin_handler_func() can be defined which gets called
  209. by the compiler on tags which can't be resolved internally or by plugins.
  210. The default_plugin_handler() can map tags to plugins on the fly.
  211. New getters/setters
  212. The following setters/getters will be part of the official
  213. documentation, and will be strongly recommended. Direct property
  214. access will still work for the foreseeable future... it will be
  215. transparently routed through the setters/getters, and consequently a
  216. bit slower.
  217. array|string getTemplateDir( [string $index] )
  218. replaces $smarty->template_dir; and $smarty->template_dir[$index];
  219. Smarty setTemplateDir( array|string $path )
  220. replaces $smarty->template_dir = "foo"; and $smarty->template_dir =
  221. array("foo", "bar");
  222. Smarty addTemplateDir( array|string $path, [string $index])
  223. replaces $smarty->template_dir[] = "bar"; and
  224. $smarty->template_dir[$index] = "bar";
  225. array|string getConfigDir( [string $index] )
  226. replaces $smarty->config_dir; and $smarty->config_dir[$index];
  227. Smarty setConfigDir( array|string $path )
  228. replaces $smarty->config_dir = "foo"; and $smarty->config_dir =
  229. array("foo", "bar");
  230. Smarty addConfigDir( array|string $path, [string $index])
  231. replaces $smarty->config_dir[] = "bar"; and
  232. $smarty->config_dir[$index] = "bar";
  233. array getPluginsDir()
  234. replaces $smarty->plugins_dir;
  235. Smarty setPluginsDir( array|string $path )
  236. replaces $smarty->plugins_dir = "foo";
  237. Smarty addPluginsDir( array|string $path )
  238. replaces $smarty->plugins_dir[] = "bar";
  239. string getCompileDir()
  240. replaces $smarty->compile_dir;
  241. Smarty setCompileDir( string $path )
  242. replaces $smarty->compile_dir = "foo";
  243. string getCacheDir()
  244. replaces $smarty->cache_dir;
  245. Smarty setCacheDir( string $path )
  246. replaces $smarty->cache_dir;