001: Smarty 3.1 Notes
002: ================
003:
004: Smarty 3.1 is a departure from 2.0 compatibility. Most notably, all
005: backward compatibility has been moved to a separate class file named
006: SmartyBC.class.php. If you require compatibility with 2.0, you will
007: need to use this class.
008:
009: Some differences from 3.0 are also present. 3.1 begins the journey of
010: requiring setters/getters for property access. So far this is only
011: implemented on the five directory properties: template_dir,
012: plugins_dir, configs_dir, compile_dir and cache_dir. These properties
013: are now protected, it is required to use the setters/getters instead.
014: That said, direct property access will still work, however slightly
015: slower since they will now fall through __set() and __get() and in
016: turn passed through the setter/getter methods. 3.2 will exhibit a full
017: list of setter/getter methods for all (currently) public properties,
018: so code-completion in your IDE will work as expected.
019:
020: There is absolutely no PHP allowed in templates any more. All
021: deprecated features of Smarty 2.0 are gone. Again, use the SmartyBC
022: class if you need any backward compatibility.
023:
024: Internal Changes
025:
026: Full UTF-8 Compatibility
027:
028: The plugins shipped with Smarty 3.1 have been rewritten to fully
029: support UTF-8 strings if Multibyte String is available. Without
030: MBString UTF-8 cannot be handled properly. For those rare cases where
031: templates themselves have to juggle encodings, the new modifiers
032: to_charset and from_charset may come in handy.
033:
034: Plugin API and Performance
035:
036: All Plugins (modifiers, functions, blocks, resources,
037: default_template_handlers, etc) are now receiving the
038: Smarty_Internal_Template instance, where they were supplied with the
039: Smarty instance in Smarty 3.0. *. As The Smarty_Internal_Template
040: mimics the behavior of Smarty, this API simplification should not
041: require any changes to custom plugins.
042:
043: The plugins shipped with Smarty 3.1 have been rewritten for better
044: performance. Most notably {html_select_date} and {html_select_time}
045: have been improved vastly. Performance aside, plugins have also been
046: reviewed and generalized in their API. {html_select_date} and
047: {html_select_time} now share almost all available options.
048:
049: The escape modifier now knows the $double_encode option, which will
050: prevent entities from being encoded again.
051:
052: The capitalize modifier now know the $lc_rest option, which makes sure
053: all letters following a captial letter are lower-cased.
054:
055: The count_sentences modifier now accepts (.?!) as
056: legitimate endings of a sentence - previously only (.) was
057: accepted
058:
059: The new unescape modifier is there to reverse the effects of the
060: escape modifier. This applies to the escape formats html, htmlall and
061: entity.
062:
063: default_template_handler_func
064:
065: The invocation of $smarty->$default_template_handler_func had to be
066: altered. Instead of a Smarty_Internal_Template, the fifth argument is
067: now provided with the Smarty instance. New footprint:
068:
069:
070: /**
071: * Default Template Handler
072: *
073: * called when Smarty's file: resource is unable to load a requested file
074: *
075: * @param string $type resource type (e.g. "file", "string", "eval", "resource")
076: * @param string $name resource name (e.g. "foo/bar.tpl")
077: * @param string &$content template's content
078: * @param integer &$modified template's modification time
079: * @param Smarty $smarty Smarty instance
080: * @return string|boolean path to file or boolean true if $content and $modified
081: * have been filled, boolean false if no default template
082: * could be loaded
083: */
084: function default_template_handler_func($type, $name, &$content, &$modified, Smarty $smarty) {
085: if (false) {
086: // return corrected filepath
087: return "/tmp/some/foobar.tpl";
088: } elseif (false) {
089: // return a template directly
090: $content = "the template source";
091: $modified = time();
092: return true;
093: } else {
094: // tell smarty that we failed
095: return false;
096: }
097: }
098:
099: 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;
307: