306 lines
11 KiB
Text
306 lines
11 KiB
Text
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.
|
|
|
|
Addressing 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;
|