aboutsummaryrefslogtreecommitdiffstats
path: root/lib/smarty/SMARTY_3.1_NOTES.txt
diff options
context:
space:
mode:
Diffstat (limited to 'lib/smarty/SMARTY_3.1_NOTES.txt')
-rw-r--r--lib/smarty/SMARTY_3.1_NOTES.txt306
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;