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