diff options
Diffstat (limited to 'lib/smarty/SMARTY_3.1_NOTES.txt')
| -rw-r--r-- | lib/smarty/SMARTY_3.1_NOTES.txt | 306 |
1 files changed, 0 insertions, 306 deletions
diff --git a/lib/smarty/SMARTY_3.1_NOTES.txt b/lib/smarty/SMARTY_3.1_NOTES.txt deleted file mode 100644 index e56e56f67..000000000 --- a/lib/smarty/SMARTY_3.1_NOTES.txt +++ /dev/null @@ -1,306 +0,0 @@ -Smarty 3.1 Notes -================ - -Smarty 3.1 is a departure from 2.0 compatibility. Most notably, all -backward compatibility has been moved to a separate class file named -SmartyBC.class.php. If you require compatibility with 2.0, you will -need to use this class. - -Some differences from 3.0 are also present. 3.1 begins the journey of -requiring setters/getters for property access. So far this is only -implemented on the five directory properties: template_dir, -plugins_dir, configs_dir, compile_dir and cache_dir. These properties -are now protected, it is required to use the setters/getters instead. -That said, direct property access will still work, however slightly -slower since they will now fall through __set() and __get() and in -turn passed through the setter/getter methods. 3.2 will exhibit a full -list of setter/getter methods for all (currently) public properties, -so code-completion in your IDE will work as expected. - -There is absolutely no PHP allowed in templates any more. All -deprecated features of Smarty 2.0 are gone. Again, use the SmartyBC -class if you need any backward compatibility. - -Internal Changes - - Full UTF-8 Compatibility - -The plugins shipped with Smarty 3.1 have been rewritten to fully -support UTF-8 strings if Multibyte String is available. Without -MBString UTF-8 cannot be handled properly. For those rare cases where -templates themselves have to juggle encodings, the new modifiers -to_charset and from_charset may come in handy. - - Plugin API and Performance - -All Plugins (modifiers, functions, blocks, resources, -default_template_handlers, etc) are now receiving the -Smarty_Internal_Template instance, where they were supplied with the -Smarty instance in Smarty 3.0. *. As The Smarty_Internal_Template -mimics the behavior of Smarty, this API simplification should not -require any changes to custom plugins. - -The plugins shipped with Smarty 3.1 have been rewritten for better -performance. Most notably {html_select_date} and {html_select_time} -have been improved vastly. Performance aside, plugins have also been -reviewed and generalized in their API. {html_select_date} and -{html_select_time} now share almost all available options. - -The escape modifier now knows the $double_encode option, which will -prevent entities from being encoded again. - -The capitalize modifier now know the $lc_rest option, which makes sure -all letters following a captial letter are lower-cased. - -The count_sentences modifier now accepts (.?!) as -legitimate endings of a sentence - previously only (.) was -accepted - -The new unescape modifier is there to reverse the effects of the -escape modifier. This applies to the escape formats html, htmlall and -entity. - - default_template_handler_func - -The invocation of $smarty->$default_template_handler_func had to be -altered. Instead of a Smarty_Internal_Template, the fifth argument is -now provided with the Smarty instance. New footprint: - - -/** - * Default Template Handler - * - * called when Smarty's file: resource is unable to load a requested file - * - * @param string $type resource type (e.g. "file", "string", "eval", "resource") - * @param string $name resource name (e.g. "foo/bar.tpl") - * @param string &$content template's content - * @param integer &$modified template's modification time - * @param Smarty $smarty Smarty instance - * @return string|boolean path to file or boolean true if $content and $modified - * have been filled, boolean false if no default template - * could be loaded - */ -function default_template_handler_func($type, $name, &$content, &$modified, Smarty $smarty) { - if (false) { - // return corrected filepath - return "/tmp/some/foobar.tpl"; - } elseif (false) { - // return a template directly - $content = "the template source"; - $modified = time(); - return true; - } else { - // tell smarty that we failed - return false; - } -} - - Stuff done to the compiler - -Many performance improvements have happened internally. One notable -improvement is that all compiled templates are now handled as PHP -functions. This speeds up repeated templates tremendously, as each one -calls an (in-memory) PHP function instead of performing another file -include/scan. - -New Features - - Template syntax - - {block}..{/block} - -The {block} tag has a new hide option flag. It does suppress the block -content if no corresponding child block exists. -EXAMPLE: -parent.tpl -{block name=body hide} child content "{$smarty.block.child}" was -inserted {block} -In the above example the whole block will be suppressed if no child -block "body" is existing. - - {setfilter}..{/setfilter} - -The new {setfilter} block tag allows the definition of filters which -run on variable output. -SYNTAX: -{setfilter filter1|filter2|filter3....} -Smarty3 will lookup up matching filters in the following search order: -1. varibale filter plugin in plugins_dir. -2. a valid modifier. A modifier specification will also accept -additional parameter like filter2:'foo' -3. a PHP function -{/setfilter} will turn previous filter setting off again. -{setfilter} tags can be nested. -EXAMPLE: -{setfilter filter1} - {$foo} - {setfilter filter2} - {$bar} - {/setfilter} - {$buh} -{/setfilter} -{$blar} -In the above example filter1 will run on the output of $foo, filter2 -on $bar, filter1 again on $buh and no filter on $blar. -NOTES: -- {$foo nofilter} will suppress the filters -- These filters will run in addition to filters defined by -registerFilter('variable',...), autoLoadFilter('variable',...) and -defined default modifier. -- {setfilter} will effect only the current template, not included -subtemplates. - - Resource API - -Smarty 3.1 features a new approach to resource management. The -Smarty_Resource API allows simple, yet powerful integration of custom -resources for templates and configuration files. It offers simple -functions for loading data from a custom resource (e.g. database) as -well as define new template types adhering to the special -non-compiling (e,g, plain php) and non-compile-caching (e.g. eval: -resource type) resources. - -See demo/plugins/resource.mysql.php for an example custom database -resource. - -Note that old-fashioned registration of callbacks for resource -management has been deprecated but is still possible with SmartyBC. - - CacheResource API - -In line with the Resource API, the CacheResource API offers a more -comfortable handling of output-cache data. With the -Smarty_CacheResource_Custom accessing databases is made simple. With -the introduction of Smarty_CacheResource_KeyValueStore the -implementation of resources like memcache or APC became a no-brainer; -simple hash-based storage systems are now supporting hierarchical -output-caches. - -See demo/plugins/cacheresource.mysql.php for an example custom -database CacheResource. -See demo/plugins/cacheresource.memcache.php for an example custom -memcache CacheResource using the KeyValueStore helper. - -Note that old-fashioned registration of $cache_handler is not possible -anymore. As the functionality had not been ported to Smarty 3.0.x -properly, it has been dropped from 3.1 completely. - -Locking facilities have been implemented to avoid concurrent cache -generation. Enable cache locking by setting -$smarty->cache_locking = true; - - Relative Paths in Templates (File-Resource) - -As of Smarty 3.1 {include file="../foo.tpl"} and {include -file="./foo.tpl"} will resolve relative to the template they're in. -Relative paths are available with {include file="..."} and -{extends file="..."}. As $smarty->fetch('../foo.tpl') and -$smarty->fetch('./foo.tpl') cannot be relative to a template, an -exception is thrown. - - Adressing a specific $template_dir - -Smarty 3.1 introduces the $template_dir index notation. -$smarty->fetch('[foo]bar.tpl') and {include file="[foo]bar.tpl"} -require the template bar.tpl to be loaded from $template_dir['foo']; -Smarty::setTemplateDir() and Smarty::addTemplateDir() offer ways to -define indexes along with the actual directories. - - Mixing Resources in extends-Resource - -Taking the php extends: template resource one step further, it is now -possible to mix resources within an extends: call like -$smarty->fetch("extends:file:foo.tpl|db:bar.tpl"); - -To make eval: and string: resources available to the inheritance -chain, eval:base64:TPL_STRING and eval:urlencode:TPL_STRING have been -introduced. Supplying the base64 or urlencode flags will trigger -decoding the TPL_STRING in with either base64_decode() or urldecode(). - - extends-Resource in template inheritance - -Template based inheritance may now inherit from php's extends: -resource like {extends file="extends:foo.tpl|db:bar.tpl"}. - - New Smarty property escape_html - -$smarty->escape_html = true will autoescape all template variable -output by calling htmlspecialchars({$output}, ENT_QUOTES, -SMARTY_RESOURCE_CHAR_SET). -NOTE: -This is a compile time option. If you change the setting you must make -sure that the templates get recompiled. - - New option at Smarty property compile_check - -The automatic recompilation of modified templates can now be -controlled by the following settings: -$smarty->compile_check = COMPILECHECK_OFF (false) - template files -will not be checked -$smarty->compile_check = COMPILECHECK_ON (true) - template files will -always be checked -$smarty->compile_check = COMPILECHECK_CACHEMISS - template files will -be checked if caching is enabled and there is no existing cache file -or it has expired - - Automatic recompilation on Smarty version change - -Templates will now be automatically recompiled on Smarty version -changes to avoide incompatibillities in the compiled code. Compiled -template checked against the current setting of the SMARTY_VERSION -constant. - - default_config_handler_func() - -Analogous to the default_template_handler_func() -default_config_handler_func() has been introduced. - - default_plugin_handler_func() - -An optional default_plugin_handler_func() can be defined which gets called -by the compiler on tags which can't be resolved internally or by plugins. -The default_plugin_handler() can map tags to plugins on the fly. - -New getters/setters - -The following setters/getters will be part of the official -documentation, and will be strongly recommended. Direct property -access will still work for the foreseeable future... it will be -transparently routed through the setters/getters, and consequently a -bit slower. - -array|string getTemplateDir( [string $index] ) -replaces $smarty->template_dir; and $smarty->template_dir[$index]; -Smarty setTemplateDir( array|string $path ) -replaces $smarty->template_dir = "foo"; and $smarty->template_dir = -array("foo", "bar"); -Smarty addTemplateDir( array|string $path, [string $index]) -replaces $smarty->template_dir[] = "bar"; and -$smarty->template_dir[$index] = "bar"; - -array|string getConfigDir( [string $index] ) -replaces $smarty->config_dir; and $smarty->config_dir[$index]; -Smarty setConfigDir( array|string $path ) -replaces $smarty->config_dir = "foo"; and $smarty->config_dir = -array("foo", "bar"); -Smarty addConfigDir( array|string $path, [string $index]) -replaces $smarty->config_dir[] = "bar"; and -$smarty->config_dir[$index] = "bar"; - -array getPluginsDir() -replaces $smarty->plugins_dir; -Smarty setPluginsDir( array|string $path ) -replaces $smarty->plugins_dir = "foo"; -Smarty addPluginsDir( array|string $path ) -replaces $smarty->plugins_dir[] = "bar"; - -string getCompileDir() -replaces $smarty->compile_dir; -Smarty setCompileDir( string $path ) -replaces $smarty->compile_dir = "foo"; - -string getCacheDir() -replaces $smarty->cache_dir; -Smarty setCacheDir( string $path ) -replaces $smarty->cache_dir; |