mirror of
https://github.com/smarty-php/smarty.git
synced 2025-10-30 20:01:37 +01:00
2743 lines
97 KiB
Plaintext
2743 lines
97 KiB
Plaintext
<part id="smarty.for.programmers">
|
|
<title>Smarty For Programmers</title>
|
|
|
|
|
|
<chapter id="smarty.constants">
|
|
<title>Constants</title>
|
|
<para></para>
|
|
|
|
<sect1 id="constant.smarty.dir">
|
|
<title>SMARTY_DIR</title>
|
|
<para>
|
|
This should be the full system path to the location of the Smarty
|
|
class files. If this is not defined, then Smarty will attempt to
|
|
determine the appropriate value automatically. If defined, the path
|
|
must end with a slash.
|
|
</para>
|
|
<example>
|
|
<title>SMARTY_DIR</title>
|
|
<programlisting>
|
|
// set path to Smarty directory
|
|
define("SMARTY_DIR","/usr/local/lib/php/Smarty/");
|
|
|
|
require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
|
|
</example>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="api.variables">
|
|
<title>Variables</title>
|
|
|
|
<sect1 id="variable.template.dir">
|
|
<title>$template_dir</title>
|
|
<para>
|
|
This is the name of the default template directory. If you do
|
|
not supply a resource type when including files, they will be
|
|
found here. By default this is "./templates", meaning that it
|
|
will look for the templates directory in the same directory as
|
|
the executing php script.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
It is not recommended to put this directory under
|
|
the web server document root.
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
<sect1 id="variable.compile.dir">
|
|
<title>$compile_dir</title>
|
|
<para>
|
|
This is the name of the directory where compiled templates are
|
|
located. By default this is "./templates_c", meaning that it
|
|
will look for the compile directory in the same directory as
|
|
the executing php script.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
This setting must be either a relative or
|
|
absolute path. include_path is not used for writing files.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
It is not recommended to put this directory under
|
|
the web server document root.
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
<sect1 id="variable.config.dir">
|
|
<title>$config_dir</title>
|
|
<para>
|
|
This is the directory used to store config files used in the
|
|
templates. Default is "./configs", meaning that it will look
|
|
for the configs directory in the same directory as the
|
|
executing php script.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
It is not recommended to put this directory under
|
|
the web server document root.
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
<sect1 id="variable.plugins.dir">
|
|
<title>$plugins_dir</title>
|
|
<para>
|
|
This is the directories where Smarty will look for the plugins that it
|
|
needs. Default is "plugins" under the SMARTY_DIR. If you supply a
|
|
relative path, Smarty will first look under the SMARTY_DIR, then
|
|
relative to the cwd (current working directory), then relative to each
|
|
entry in your PHP include path.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
For best performance, do not setup your plugins_dir to have to use the
|
|
PHP include path. Use an absolute pathname, or a path relative to
|
|
SMARTY_DIR or the cwd.
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
<sect1 id="variable.debugging">
|
|
<title>$debugging</title>
|
|
<para>
|
|
This enables the <link
|
|
linkend="chapter.debugging.console">debugging console</link>.
|
|
The console is a javascript window that informs you of the
|
|
included templates and assigned variables for the current
|
|
template page.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.debug.tpl">
|
|
<title>$debug_tpl</title>
|
|
<para>
|
|
This is the name of the template file used for the debugging console. By
|
|
default, it is named debug.tpl and is located in the <link
|
|
linkend="constant.smarty.dir">SMARTY_DIR</link>.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.debugging.ctrl">
|
|
<title>$debugging_ctrl</title>
|
|
<para>
|
|
This allows alternate ways to enable debugging. NONE means no
|
|
alternate methods are allowed. URL means when the keyword
|
|
SMARTY_DEBUG is found in the QUERY_STRING, debugging is enabled
|
|
for that invocation of the script. If $debugging is true, this
|
|
value is ignored.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.global.assign">
|
|
<title>$global_assign</title>
|
|
<para>
|
|
This is a list of variables that are always implicitly assigned
|
|
to the template engine. This is handy for making global
|
|
variables or server variables available to all templates
|
|
without having to manually assign them. Each element in the
|
|
$global_assign should be either a name of the global variable,
|
|
or a key/value pair, where the key is the name of the global
|
|
array and the value is the array of variables to be assigned
|
|
from that global array. $SCRIPT_NAME is globally assigned by
|
|
default from $HTTP_SERVER_VARS.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
Server variables can be accessed through the
|
|
$smarty variable, such as {$smarty.server.SCRIPT_NAME}. See the
|
|
section on the
|
|
<link linkend="language.variables.smarty">$smarty</link> variable.
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
<sect1 id="variable.undefined">
|
|
<title>$undefined</title>
|
|
<para>
|
|
This sets the value of $undefined for Smarty, default is null.
|
|
Currently this is only used to set undefined variables in
|
|
$global_assign to a default value.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.autoload.filters">
|
|
<title>$autoload_filters</title>
|
|
<para>
|
|
If there are some filters that you wish to load on every template
|
|
invocation, you can specify them using this variable and Smarty will
|
|
automatically load them for you. The variable is an associative array
|
|
where keys are filter types and values are arrays of the filter
|
|
names. For example:
|
|
<informalexample>
|
|
<programlisting>
|
|
$smarty->autoload_filters = array('pre' => array('trim', 'stamp'),
|
|
'output' => array('convert'));
|
|
</programlisting>
|
|
</informalexample>
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.compile.check">
|
|
<title>$compile_check</title>
|
|
<para>
|
|
Upon each invocation of the PHP application, Smarty tests to
|
|
see if the current template has changed (later time stamp)
|
|
since the last time it was compiled. If it has changed, it
|
|
recompiles that template. As of 1.4.0, if the template has not
|
|
been compiled, it will compile regardless of this setting. By
|
|
default this variable is set to true. Once an application is
|
|
put into production (templates won't be changing), the
|
|
compile_check step is no longer needed. Be sure to set
|
|
$compile_check to "false" to improve performance! Note that if
|
|
you change this to "false" and a template file is changed, you
|
|
will *not* see the change since the template will not get
|
|
recompiled. If caching is enabled and compile_check is enabled,
|
|
then the cache files will get regenerated if an involved
|
|
template file was updated. See <link
|
|
linkend="variable.force.compile">$force_compile</link> or <link
|
|
linkend="api.clear.compiled.tpl">clear_compiled_tpl</link>.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.force.compile">
|
|
<title>$force_compile</title>
|
|
<para>
|
|
This forces Smarty to (re)compile templates on every
|
|
invocation. This setting overrides $compile_check. By default
|
|
this is disabled. This is handy for development and debugging.
|
|
It should never be used in a production environment. If caching
|
|
is enabled, the cache file(s) will be regenerated every time.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.caching">
|
|
<title>$caching</title>
|
|
<para>
|
|
This tells Smarty whether or not to cache the output of the templates.
|
|
By default this is set to 0, or disabled. If your templates generate
|
|
redundant redundant content, it is advisable to turn on caching. This
|
|
will result in significant performance gains. You can also have multiple
|
|
caches for the same template. A value of 1 or 2 enables caching. 1 tells
|
|
Smarty to use the current $cache_lifetime variable to determine if the
|
|
cache has expired. A value of 2 tells Smarty to use the cache_lifetime
|
|
value at the time the cache was generated. This way you can set the
|
|
cache_lifetime just before fetching the template to have granular
|
|
control over when that particular cache expires. See also <link
|
|
linkend="api.is.cached">is_cached</link>.
|
|
</para>
|
|
<para>
|
|
If $compile_check is enabled, the cached content will be regenerated if
|
|
any of the templates or config files that are part of this cache are
|
|
changed. If $force_compile is enabled, the cached content will always be
|
|
regenerated.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.cache.dir">
|
|
<title>$cache_dir</title>
|
|
<para>
|
|
This is the name of the directory where template caches are
|
|
stored. By default this is "./cache", meaning that it will look
|
|
for the cache directory in the same directory as the executing
|
|
php script. You can also use your own custom cache handler
|
|
function to control cache files, which will ignore this
|
|
setting.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
This setting must be either a relative or
|
|
absolute path. include_path is not used for writing files.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
It is not recommended to put this directory under
|
|
the web server document root.
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
<sect1 id="variable.cache.lifetime">
|
|
<title>$cache_lifetime</title>
|
|
<para>
|
|
This is the length of time in seconds that a template cache is valid.
|
|
Once this time has expired, the cache will be regenerated. $caching must
|
|
be set to "true" for $cache_lifetime to have any purpose. A value of -1
|
|
will force the cache to never expire. A value of 0 will cause the cache
|
|
to always regenerate (good for testing only, to disable caching a more
|
|
efficient method is to set <link
|
|
linkend="variable.caching">$caching</link> = false.)
|
|
</para>
|
|
<para>
|
|
If <link linkend="variable.force.compile">$force_compile</link> is
|
|
enabled, the cache files will be regenerated every time, effectively
|
|
disabling caching. You can clear all the cache files with the <link
|
|
linkend="api.clear.all.cache">clear_all_cache()</link> function, or
|
|
individual cache files (or groups) with the <link
|
|
linkend="api.clear.cache">clear_cache()</link> function.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
If you want to give certain templates their own cache lifetime, you could
|
|
do this by setting <link linkend="variable.caching">$caching</link> = 2,
|
|
then set $cache_lifetime to a unique value just before calling display()
|
|
or fetch().
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
<sect1 id="variable.cache.handler.func">
|
|
<title>$cache_handler_func</title>
|
|
<para>
|
|
You can supply a custom function to handle cache files instead
|
|
of using the built-in method using the $cache_dir. See the
|
|
custom cache handler function section for details.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.cache.modified.check">
|
|
<title>$cache_modified_check</title>
|
|
<para>
|
|
If set to true, Smarty will respect the If-Modified-Since
|
|
header sent from the client. If the cached file timestamp has
|
|
not changed since the last visit, then a "304 Not Modified"
|
|
header will be sent instead of the content. This works only on
|
|
cached content without <command>insert</command> tags.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.default.template.handler.func">
|
|
<title>$default_template_handler_func</title>
|
|
<para>
|
|
This function is called when a template cannot be obtained from
|
|
its resource.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.php.handling">
|
|
<title>$php_handling</title>
|
|
<para>
|
|
This tells Smarty how to handle PHP code embedded in the
|
|
tempalates. There are four possible settings, default being
|
|
SMARTY_PHP_PASSTHRU. Note that this does NOT affect php code
|
|
within <link linkend="language.function.php">{php}{/php}</link>
|
|
tags in the template.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>SMARTY_PHP_PASSTHRU - Smarty echos tags as-is.</para></listitem>
|
|
<listitem><para>SMARTY_PHP_QUOTE - Smarty quotes the tags as
|
|
html entities.</para></listitem>
|
|
<listitem><para>SMARTY_PHP_REMOVE - Smarty removes the tags from
|
|
the templates.</para></listitem>
|
|
<listitem><para>SMARTY_PHP_ALLOW - Smarty will execute the tags
|
|
as PHP code.</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
NOTE: Embedding PHP code into templates is highly discouraged.
|
|
Use <link linkend="language.custom.functions">custom functions</link> or
|
|
<link linkend="language.modifiers">modifiers</link> instead.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.security">
|
|
<title>$security</title>
|
|
<para>
|
|
$security true/false, default is false. Security is good for
|
|
situations when you have untrusted parties editing the templates
|
|
(via ftp for example) and you want to reduce the risk of system
|
|
security compromises through the template language. Turning on
|
|
security enforces the following rules to the template language,
|
|
unless specifially overridden with $security_settings:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>If $php_handling is set to SMARTY_PHP_ALLOW, this is
|
|
implicitly changed to SMARTY_PHP_PASSTHRU</para></listitem>
|
|
<listitem><para>PHP functions are not allowed in IF statements,
|
|
except those specified in the $security_settings</para></listitem>
|
|
<listitem><para>templates can only be included from directories
|
|
listed in the $secure_dir array</para></listitem>
|
|
<listitem><para>local files can only be fetched from directories
|
|
listed in the $secure_dir array using {fetch}</para></listitem>
|
|
<listitem><para>{php}{/php} tags are not allowed</para></listitem>
|
|
<listitem><para>PHP functions are not allowed as modifiers, except
|
|
those specified in the $security_settings</para></listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
<sect1 id="variable.secure.dir">
|
|
<title>$secure_dir</title>
|
|
<para>
|
|
This is an array of all local directories that are considered
|
|
secure. {include} and {fetch} use this when security is enabled.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.security.settings">
|
|
<title>$security_settings</title>
|
|
<para>
|
|
These are used to override or specify the security settings when
|
|
security is enabled. These are the possible settings:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>PHP_HANDLING - true/false. If set to true, the
|
|
$php_handling setting is not checked for security.</para></listitem>
|
|
<listitem><para>IF_FUNCS - This is an array of the names of permitted
|
|
PHP functions in IF statements.</para></listitem>
|
|
<listitem><para>INCLUDE_ANY - true/false. If set to true, any
|
|
template can be included from the file system, regardless of the
|
|
$secure_dir list.</para></listitem>
|
|
<listitem><para>PHP_TAGS - true/false. If set to true, {php}{/php}
|
|
tags are permitted in the templates.</para></listitem>
|
|
<listitem><para>MODIFIER_FUNCS - This is an array of the names of permitted
|
|
PHP functions used as variable modifiers.</para></listitem>
|
|
</itemizedlist>
|
|
</sect1>
|
|
<sect1 id="variable.trusted.dir">
|
|
<title>$trusted_dir</title>
|
|
<para>
|
|
$trusted_dir is only for use when $security is enabled. This is an array
|
|
of all directories that are considered trusted. Trusted directories are
|
|
where you keep php scripts that are executed directly from the templates
|
|
with <link linkend="language.function.include.php">{include_php}</link>.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.left.delimiter">
|
|
<title>$left_delimiter</title>
|
|
<para>
|
|
This is the left delimiter used by the template language.
|
|
Default is "{".
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.right.delimiter">
|
|
<title>$right_delimiter</title>
|
|
<para>
|
|
This is the right delimiter used by the template language.
|
|
Default is "}".
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.show.info.header">
|
|
<title>$show_info_header</title>
|
|
<para>
|
|
Shows an HTML comment at the beginning of the templates output,
|
|
displaying smarty version and date generated. Default is false.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.show.info.include">
|
|
<title>$show_info_include</title>
|
|
<para>
|
|
Shows an HTML comment before and after each included template.
|
|
Default is false.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.compiler.class">
|
|
<title>$compiler_class</title>
|
|
<para>
|
|
Specifies the name of the compiler class that Smarty will use
|
|
to compile the templates. The default is 'Smarty_Compiler'. For
|
|
advanced users only.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.request.vars.order">
|
|
<title>$request_vars_order</title>
|
|
<para>
|
|
The order in which request variables are registered, similar to
|
|
variables_order in php.ini
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.compile.id">
|
|
<title>$compile_id</title>
|
|
<para>
|
|
Persistant compile identifier. As an alternative to passing the same
|
|
compile_id to each and every function call, you can set this compile_id
|
|
and it will be used implicitly thereafter.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.use.sub.dirs">
|
|
<title>$use_sub_dirs</title>
|
|
<para>
|
|
Set this to false if your PHP environment does not allow the creation of
|
|
sub directories by Smarty. Sub directories are more efficient, so use them
|
|
if you can.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="variable.default.modifiers">
|
|
<title>$default_modifiers</title>
|
|
<para>
|
|
This is an array of modifiers to implicitly apply to every variable in a
|
|
template. For example, to HTML-escape every variable by default, use
|
|
array('escape:"htmlall"'); To make a variable exempt from default
|
|
modifiers, pass the special "nodefaults" modifier to it, such as
|
|
{$var|nodefaults}.
|
|
</para>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="api.functions">
|
|
<title>Methods</title>
|
|
<sect1 id="api.append">
|
|
<title>append</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>append</function></funcdef>
|
|
<paramdef>mixed <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>void <function>append</function></funcdef>
|
|
<paramdef>string <parameter>varname</parameter></paramdef>
|
|
<paramdef>mixed <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This is used to append data to variables in the template. You
|
|
can explicitly pass name/value pairs, or associative arrays
|
|
containing the name/value pairs.
|
|
</para>
|
|
<example>
|
|
<title>append</title>
|
|
<programlisting>
|
|
// passing name/value pairs
|
|
$smarty->append("Name","Fred");
|
|
$smarty->append("Address",$address);
|
|
|
|
// passing an associative array
|
|
$smarty->append(array("city" => "Lincoln","state" => "Nebraska"));</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.append.by.ref">
|
|
<title>append_by_ref</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>append_by_ref</function></funcdef>
|
|
<paramdef>string <parameter>varname</parameter></paramdef>
|
|
<paramdef>mixed <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This is used to append values to the templates by reference instead of
|
|
making a copy. See the PHP manual on variable referencing for an explanation.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
append_by_ref() is more efficient than append() since it does not create
|
|
an in-memory copy of the variable. Instead it refers to the actual
|
|
variable in the memory heap. Be aware if you alter the original variable
|
|
after it is assigned, the assigned variable sees the changes! PHP 5.0
|
|
will take care of referencing automatically, so this function acts as a
|
|
workaround.
|
|
</para>
|
|
</note>
|
|
<example>
|
|
<title>append_by_ref</title>
|
|
<programlisting>
|
|
// appending name/value pairs
|
|
$smarty->append_by_ref("Name",$myname);
|
|
$smarty->append_by_ref("Address",$address);</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.assign">
|
|
<title>assign</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>assign</function></funcdef>
|
|
<paramdef>mixed <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>void <function>assign</function></funcdef>
|
|
<paramdef>string <parameter>varname</parameter></paramdef>
|
|
<paramdef>mixed <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This is used to assign values to the templates. You can
|
|
explicitly pass name/value pairs, or associative arrays
|
|
containing the name/value pairs.
|
|
</para>
|
|
<example>
|
|
<title>assign</title>
|
|
<programlisting>
|
|
// passing name/value pairs
|
|
$smarty->assign("Name","Fred");
|
|
$smarty->assign("Address",$address);
|
|
|
|
// passing an associative array
|
|
$smarty->assign(array("city" => "Lincoln","state" => "Nebraska"));</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.assign.by.ref">
|
|
<title>assign_by_ref</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>assign_by_ref</function></funcdef>
|
|
<paramdef>string <parameter>varname</parameter></paramdef>
|
|
<paramdef>mixed <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This is used to assign values to the templates by reference instead of
|
|
making a copy. See the PHP manual on variable referencing for an explanation.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
assign_by_ref() is more efficient than assign() since it does not create
|
|
an in-memory copy of the variable. Instead it refers to the actual
|
|
variable in the memory heap. Be aware if you alter the original variable
|
|
after it is assigned, the assigned variable sees the changes! PHP 5.0
|
|
will take care of referencing automatically, so this function acts as a
|
|
workaround.
|
|
</para>
|
|
</note>
|
|
<example>
|
|
<title>assign_by_ref</title>
|
|
<programlisting>
|
|
// passing name/value pairs
|
|
$smarty->assign_by_ref("Name",$myname);
|
|
$smarty->assign_by_ref("Address",$address);</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.clear.all.assign">
|
|
<title>clear_all_assign</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>clear_all_assign</function></funcdef>
|
|
<paramdef><parameter></parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This clears the values of all assigned variables.
|
|
</para>
|
|
<example>
|
|
<title>clear_all_assign</title>
|
|
<programlisting>
|
|
// clear all assigned variables
|
|
$smarty->clear_all_assign();</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.clear.all.cache">
|
|
<title>clear_all_cache</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>clear_all_cache</function></funcdef>
|
|
<paramdef>int <parameter>expire time</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This clears the entire template cache. As an optional
|
|
parameter, you can supply a minimum age in seconds the cache
|
|
files must be before they will get cleared.
|
|
</para>
|
|
<example>
|
|
<title>clear_all_cache</title>
|
|
<programlisting>
|
|
// clear the entire cache
|
|
$smarty->clear_all_cache();</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.clear.assign">
|
|
<title>clear_assign</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>clear_assign</function></funcdef>
|
|
<paramdef>string <parameter>var</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This clears the value of an assigned variable. This
|
|
can be a single value, or an array of values.
|
|
</para>
|
|
<example>
|
|
<title>clear_assign</title>
|
|
<programlisting>
|
|
// clear a single variable
|
|
$smarty->clear_assign("Name");
|
|
|
|
// clear multiple variables
|
|
$smarty->clear_assign(array("Name","Address","Zip"));</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.clear.cache">
|
|
<title>clear_cache</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>clear_cache</function></funcdef>
|
|
<paramdef>string <parameter>template</parameter></paramdef>
|
|
<paramdef>string <parameter><optional>cache id</optional></parameter></paramdef>
|
|
<paramdef>string <parameter><optional>compile id</optional></parameter></paramdef>
|
|
<paramdef>int <parameter><optional>expire time</optional></parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This clears the cache for a specific template. If you have
|
|
multiple caches for this template, you can clear a specific
|
|
cache by supplying the cache id as the second parameter. You
|
|
can also pass a compile id as a third parameter. You can "group"
|
|
templates together so they can be removed as a group. See the
|
|
<link linkend="caching">caching section</link> for more
|
|
information. As an optional fourth parameter, you can supply a
|
|
minimum age in seconds the cache file must be before it will
|
|
get cleared.
|
|
</para>
|
|
<example>
|
|
<title>clear_cache</title>
|
|
<programlisting>
|
|
// clear the cache for a template
|
|
$smarty->clear_cache("index.tpl");
|
|
|
|
// clear the cache for a particular cache id in an multiple-cache template
|
|
$smarty->clear_cache("index.tpl","CACHEID");</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.clear.compiled.tpl">
|
|
<title>clear_compiled_tpl</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>clear_compiled_tpl</function></funcdef>
|
|
<paramdef>string <parameter>tpl_file</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This clears the compiled version of the specified template
|
|
resource, or all compiled template files if one is not specified.
|
|
This function is for advanced use only, not normally needed.
|
|
</para>
|
|
<example>
|
|
<title>clear_compiled_tpl</title>
|
|
<programlisting>
|
|
// clear a specific template resource
|
|
$smarty->clear_compiled_tpl("index.tpl");
|
|
|
|
// clear entire compile directory
|
|
$smarty->clear_compiled_tpl();</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.display">
|
|
<title>display</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>display</function></funcdef>
|
|
<paramdef>string <parameter>template</parameter></paramdef>
|
|
<paramdef>string <parameter><optional>cache_id</optional></parameter></paramdef>
|
|
<paramdef>string <parameter><optional>compile_id</optional></parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This displays the template. Supply a valid <link
|
|
linkend="template.resources">template resource</link>
|
|
type and path. As an optional second parameter, you can pass a
|
|
cache id. See the <link linkend="caching">caching
|
|
section</link> for more information.
|
|
</para>
|
|
<para>
|
|
As an optional third parameter, you can pass a compile id. This
|
|
is in the event that you want to compile different versions of
|
|
the same template, such as having separate templates compiled
|
|
for different languages. Another use for compile_id is when you
|
|
use more than one $template_dir but only one $compile_dir. Set
|
|
a separate compile_id for each $template_dir, otherwise
|
|
templates of the same name will overwrite each other. You can
|
|
also set the <link
|
|
linkend="variable.compile.id">$compile_id</link> variable once
|
|
instead of passing this to each call to display().
|
|
</para>
|
|
<example>
|
|
<title>display</title>
|
|
<programlisting>
|
|
include("Smarty.class.php");
|
|
$smarty = new Smarty;
|
|
$smarty->caching = true;
|
|
|
|
// only do db calls if cache doesn't exist
|
|
if(!$smarty->is_cached("index.tpl"))
|
|
{
|
|
|
|
// dummy up some data
|
|
$address = "245 N 50th";
|
|
$db_data = array(
|
|
"City" => "Lincoln",
|
|
"State" => "Nebraska",
|
|
"Zip" = > "68502"
|
|
);
|
|
|
|
$smarty->assign("Name","Fred");
|
|
$smarty->assign("Address",$address);
|
|
$smarty->assign($db_data);
|
|
|
|
}
|
|
|
|
// display the output
|
|
$smarty->display("index.tpl");</programlisting>
|
|
</example>
|
|
<para>
|
|
Use the syntax for <link
|
|
linkend="template.resources">template resources</link> to
|
|
display files outside of the $template_dir directory.
|
|
</para>
|
|
<example>
|
|
<title>function display template resource examples</title>
|
|
<programlisting>
|
|
// absolute filepath
|
|
$smarty->display("/usr/local/include/templates/header.tpl");
|
|
|
|
// absolute filepath (same thing)
|
|
$smarty->display("file:/usr/local/include/templates/header.tpl");
|
|
|
|
// windows absolute filepath (MUST use "file:" prefix)
|
|
$smarty->display("file:C:/www/pub/templates/header.tpl");
|
|
|
|
// include from template resource named "db"
|
|
$smarty->display("db:header.tpl");</programlisting>
|
|
</example>
|
|
|
|
</sect1>
|
|
<sect1 id="api.fetch">
|
|
<title>fetch</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>fetch</function></funcdef>
|
|
<paramdef>string <parameter>template</parameter></paramdef>
|
|
<paramdef>string <parameter><optional>cache_id</optional></parameter></paramdef>
|
|
<paramdef>string <parameter><optional>compile_id</optional></parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This returns the template output instead of displaying it.
|
|
Supply a valid <link
|
|
linkend="template.resources">template resource</link>
|
|
type and path. As an optional second parameter, you can pass a
|
|
cache id. See the <link linkend="caching">caching
|
|
section</link> for more information.
|
|
</para>
|
|
<para>
|
|
As an optional third parameter, you can pass a compile id. This
|
|
is in the event that you want to compile different versions of
|
|
the same template, such as having separate templates compiled
|
|
for different languages. Another use for compile_id is when you
|
|
use more than one $template_dir but only one $compile_dir. Set
|
|
a separate compile_id for each $template_dir, otherwise
|
|
templates of the same name will overwrite each other. You can
|
|
also set the <link
|
|
linkend="variable.compile.id">$compile_id</link> variable once
|
|
instead of passing this to each call to fetch().
|
|
</para>
|
|
<example>
|
|
<title>fetch</title>
|
|
<programlisting>
|
|
include("Smarty.class.php");
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
|
|
// only do db calls if cache doesn't exist
|
|
if(!$smarty->is_cached("index.tpl"))
|
|
{
|
|
|
|
// dummy up some data
|
|
$address = "245 N 50th";
|
|
$db_data = array(
|
|
"City" => "Lincoln",
|
|
"State" => "Nebraska",
|
|
"Zip" = > "68502"
|
|
);
|
|
|
|
$smarty->assign("Name","Fred");
|
|
$smarty->assign("Address",$address);
|
|
$smarty->assign($db_data);
|
|
|
|
}
|
|
|
|
// capture the output
|
|
$output = $smarty->fetch("index.tpl");
|
|
|
|
// do something with $output here
|
|
|
|
echo $output;</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.get.template.vars">
|
|
<title>get_template_vars</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>array <function>get_template_vars</function></funcdef>
|
|
<paramdef><parameter></parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This gets an array of the currently assigned template vars.
|
|
</para>
|
|
<example>
|
|
<title>get_template_vars</title>
|
|
<programlisting>
|
|
// get all assigned template vars
|
|
$tpl_vars = $smarty->get_template_vars();
|
|
|
|
// take a look at them
|
|
var_dump($tpl_vars);</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.is.cached">
|
|
<title>is_cached</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>is_cached</function></funcdef>
|
|
<paramdef>string <parameter>template</parameter></paramdef>
|
|
<paramdef>[string <parameter>cache_id</parameter>]</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This returns true if there is a valid cache for this template.
|
|
This only works if <link
|
|
linkend="variable.caching">caching</link> is set to true.
|
|
</para>
|
|
<example>
|
|
<title>is_cached</title>
|
|
<programlisting>
|
|
$smarty->caching = true;
|
|
|
|
if(!$smarty->is_cached("index.tpl")) {
|
|
// do database calls, assign vars here
|
|
}
|
|
|
|
$smarty->display("index.tpl");</programlisting>
|
|
</example>
|
|
<para>
|
|
You can also pass a cache id as an an optional second parameter
|
|
in case you want multiple caches for the given template.
|
|
</para>
|
|
<example>
|
|
<title>is_cached with multiple-cache template</title>
|
|
<programlisting>
|
|
$smarty->caching = true;
|
|
|
|
if(!$smarty->is_cached("index.tpl","FrontPage")) {
|
|
// do database calls, assign vars here
|
|
}
|
|
|
|
$smarty->display("index.tpl","FrontPage");</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.load.filter">
|
|
<title>load_filter</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>load_filter</function></funcdef>
|
|
<paramdef>string <parameter>type</parameter></paramdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function can be used to load a filter plugin. The first
|
|
argument specifies the type of the filter to load and can be one
|
|
of the following: 'pre', 'post', or 'output'. The second argument
|
|
specifies the name of the filter plugin, for example, 'trim'.
|
|
</para>
|
|
<example>
|
|
<title>loading filter plugins</title>
|
|
<programlisting>
|
|
$smarty->load_filter('pre', 'trim'); // load prefilter named 'trim'
|
|
$smarty->load_filter('pre', 'datefooter'); // load another prefilter named 'datefooter'
|
|
$smarty->load_filter('output', 'compress'); // load output filter named 'compress'</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.register.block">
|
|
<title>register_block</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>register_block</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
<paramdef>string <parameter>impl</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically register block functions plugins.
|
|
Pass in the block function name, followed by the PHP
|
|
function name that implements it.
|
|
</para>
|
|
<example>
|
|
<title>register_block</title>
|
|
<programlisting>
|
|
/* PHP */
|
|
$smarty->register_block("translate", "do_translation");
|
|
|
|
function do_translation ($params, $content, &$smarty) {
|
|
if ($content) {
|
|
$lang = $params['lang'];
|
|
// do some translation with $content
|
|
echo $translation;
|
|
}
|
|
}
|
|
|
|
{* template *}
|
|
{translate lang="br"}
|
|
Hello, world!
|
|
{/translate}</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.register.compiler.function">
|
|
<title>register_compiler_function</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>register_compiler_function</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
<paramdef>string <parameter>impl</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically register a compiler function plugin.
|
|
Pass in the compiler function name, followed by the PHP
|
|
function that implements it.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="api.register.function">
|
|
<title>register_function</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>register_function</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
<paramdef>string <parameter>impl</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically register template function plugins.
|
|
Pass in the template function name, followed by the PHP
|
|
function name that implements it.
|
|
</para>
|
|
<example>
|
|
<title>register_function</title>
|
|
<programlisting>
|
|
$smarty->register_function("date_now", "print_current_date");
|
|
|
|
function print_current_date ($params) {
|
|
extract($params);
|
|
if(empty($format))
|
|
$format="%b %e, %Y";
|
|
echo strftime($format,time());
|
|
}
|
|
|
|
// now you can use this in Smarty to print the current date: {date_now}
|
|
// or, {date_now format="%Y/%m/%d"} to format it.</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.register.modifier">
|
|
<title>register_modifier</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>register_modifier</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
<paramdef>string <parameter>impl</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically register modifier plugin. Pass in the
|
|
template modifier name, followed by the PHP function that it
|
|
implements it.
|
|
</para>
|
|
<example>
|
|
<title>register_modifier</title>
|
|
<programlisting>
|
|
// let's map PHP's stripslashes function to a Smarty modifier.
|
|
|
|
$smarty->register_modifier("sslash","stripslashes");
|
|
|
|
// now you can use {$var|sslash} to strip slashes from variables</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.register.outputfilter">
|
|
<title>register_outputfilter</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>register_outputfilter</function></funcdef>
|
|
<paramdef>string <parameter>function_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically register outputfilters to operate on
|
|
a template's output before it is displayed. See
|
|
<link linkend="advanced.features.outputfilters">template output
|
|
filters</link>
|
|
for more information on how to set up an output filter function.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="api.register.postfilter">
|
|
<title>register_postfilter</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>register_postfilter</function></funcdef>
|
|
<paramdef>string <parameter>function_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically register postfilters to run templates
|
|
through after they are compiled. See <link
|
|
linkend="advanced.features.postfilters">template postfilters</link> for
|
|
more information on how to setup a postfiltering function.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="api.register.prefilter">
|
|
<title>register_prefilter</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>register_prefilter</function></funcdef>
|
|
<paramdef>string <parameter>function_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically register prefilters to run templates
|
|
through before they are compiled. See <link
|
|
linkend="advanced.features.prefilters">template prefilters</link> for
|
|
more information on how to setup a prefiltering function.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="api.register.resource">
|
|
<title>register_resource</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>register_resource</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
<paramdef>array <parameter>resource_funcs</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically register a resource plugin with Smarty.
|
|
Pass in the name of the resource and the array of PHP functions
|
|
implementing it. See
|
|
<link linkend="template.resources">template resources</link>
|
|
for more information on how to setup a function for fetching
|
|
templates.
|
|
</para>
|
|
<example>
|
|
<title>register_resource</title>
|
|
<programlisting>
|
|
$smarty->register_resource("db", array("db_get_template",
|
|
"db_get_timestamp",
|
|
"db_get_secure",
|
|
"db_get_trusted"));</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.trigger.error">
|
|
<title>trigger_error</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>trigger_error</function></funcdef>
|
|
<paramdef>string <parameter>error_msg</parameter></paramdef>
|
|
<paramdef>[int <parameter>level</parameter>]</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function can be used to output an error message using Smarty.
|
|
<parameter>level</parameter> parameter can be one of the values
|
|
used for trigger_error() PHP function, i.e. E_USER_NOTICE,
|
|
E_USER_WARNING, etc. By default it's E_USER_WARNING.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="api.template.exists">
|
|
<title>template_exists</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>template_exists</function></funcdef>
|
|
<paramdef>string <parameter>template</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This function checks whether the specified template exists. It can
|
|
accept either a path to the template on the filesystem or a
|
|
resource string specifying the template.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="api.unregister.block">
|
|
<title>unregister_block</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>unregister_block</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically unregister block function plugin.
|
|
Pass in the block function name.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="api.unregister.compiler.function">
|
|
<title>unregister_compiler_function</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>unregister_compiler_function</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically unregister a compiler function. Pass in
|
|
the name of the compiler function.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="api.unregister.function">
|
|
<title>unregister_function</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>unregister_function</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically unregister template function plugin.
|
|
Pass in the template function name.
|
|
</para>
|
|
<example>
|
|
<title>unregister_function</title>
|
|
<programlisting>
|
|
// we don't want template designers to have access to system files
|
|
|
|
$smarty->unregister_function("fetch");</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.unregister.modifier">
|
|
<title>unregister_modifier</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>unregister_modifier</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically unregister modifier plugin. Pass in the
|
|
template modifier name.
|
|
</para>
|
|
<example>
|
|
<title>unregister_modifier</title>
|
|
<programlisting>
|
|
// we don't want template designers to strip tags from elements
|
|
|
|
$smarty->unregister_modifier("strip_tags");</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="api.unregister.outputfilter">
|
|
<title>unregister_outputfilter</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>unregister_outputfilter</function></funcdef>
|
|
<paramdef>string <parameter>function_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically unregister an output filter.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="api.unregister.postfilter">
|
|
<title>unregister_postfilter</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>unregister_postfilter</function></funcdef>
|
|
<paramdef>string <parameter>function_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically unregister a postfilter.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="api.unregister.prefilter">
|
|
<title>unregister_prefilter</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>unregister_prefilter</function></funcdef>
|
|
<paramdef>string <parameter>function_name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically unregister a prefilter.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="api.unregister.resource">
|
|
<title>unregister_resource</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>unregister_resource</function></funcdef>
|
|
<paramdef>string <parameter>name</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Use this to dynamically unregister a resource plugin. Pass in the
|
|
name of the resource.
|
|
</para>
|
|
<example>
|
|
<title>unregister_resource</title>
|
|
<programlisting>
|
|
$smarty->unregister_resource("db");</programlisting>
|
|
</example>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="caching">
|
|
<title>Caching</title>
|
|
<para>
|
|
Caching is used to speed up a call to <link
|
|
linkend="api.display">display()</link> or <link
|
|
linkend="api.fetch">fetch()</link> by saving its output to a file. If a
|
|
cached version of the call is available, that is displayed instead of
|
|
regenerating the output. Caching can speed things up tremendously,
|
|
especially templates with longer computation times. Since the output of
|
|
display() or fetch() is cached, one cache file could conceivably be made up
|
|
of several template files, config files, etc.
|
|
</para>
|
|
<para>
|
|
Since templates are dynamic, it is important to be careful what you are
|
|
caching and for how long. For instance, if you are displaying the front page
|
|
of your website that does not change its content very often, it might work
|
|
well to cache this page for an hour or more. On the other hand, if you are
|
|
displaying a page with a weather map containing new information by the
|
|
minute, it would not make sense to cache this page.
|
|
</para>
|
|
<sect1 id="caching.setting.up">
|
|
<title>Setting Up Caching</title>
|
|
<para>
|
|
The first thing to do is enable caching. This is done by setting <link
|
|
linkend="variable.caching">$caching</link> = true (or 1.)
|
|
</para>
|
|
<example>
|
|
<title>enabling caching</title>
|
|
<programlisting>
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
|
|
$smarty->display('index.tpl');</programlisting>
|
|
</example>
|
|
<para>
|
|
With caching enabled, the function call to display('index.tpl') will render
|
|
the template as usual, but also saves a copy of its output to a file (a
|
|
cached copy) in the <link linkend="variable.cache.dir">$cache_dir</link>.
|
|
Upon the next call to display('index.tpl'), the cached copy will be used
|
|
instead of rendering the template again.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
The files in the $cache_dir are named similar to the template name.
|
|
Although they end in the ".php" extention, they are not really executable
|
|
php scripts. Do not edit these files!
|
|
</para>
|
|
</note>
|
|
<para>
|
|
Each cached page has a limited lifetime determined by <link
|
|
linkend="variable.cache.lifetime">$cache_lifetime</link>. The default value
|
|
is 3600 seconds, or 1 hour. After that time expires, the cache is
|
|
regenerated. It is possible to give individual caches their own expiration
|
|
time by setting $caching = 2. See the documentation on <link
|
|
linkend="variable.cache.lifetime">$cache_lifetime</link> for details.
|
|
</para>
|
|
<example>
|
|
<title>setting cache_lifetime per cache</title>
|
|
<programlisting>
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = 2; // lifetime is per cache
|
|
|
|
// set the cache_lifetime for index.tpl to 15 minutes
|
|
$smarty->cache_lifetime = 300;
|
|
$smarty->display('index.tpl');
|
|
|
|
// set the cache_lifetime for home.tpl to 1 hour
|
|
$smarty->cache_lifetime = 3600;
|
|
$smarty->display('home.tpl');
|
|
|
|
// NOTE: the following $cache_lifetime setting will not work when $caching = 2.
|
|
// The cache lifetime for home.tpl has already been set
|
|
// to 1 hour, and will no longer respect the value of $cache_lifetime.
|
|
// The home.tpl cache will still expire after 1 hour.
|
|
$smarty->cache_lifetime = 30; // 30 seconds
|
|
$smarty->display('home.tpl');</programlisting>
|
|
</example>
|
|
<para>
|
|
If <link linkend="variable.compile.check">$compile_check</link> is enabled,
|
|
every template file and config file that is involved with the cache file is
|
|
checked for modification. If any of the files have been modified since the
|
|
cache was generated, the cache is immediately regenerated. This is a slight
|
|
overhead so for optimum performance, leave $compile_check set to false.
|
|
</para>
|
|
<example>
|
|
<title>enabling $compile_check</title>
|
|
<programlisting>
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
$smarty->compile_check = true;
|
|
|
|
$smarty->display('index.tpl');</programlisting>
|
|
</example>
|
|
<para>
|
|
If <link linkend="variable.force.compile">$force_compile</link> is enabled,
|
|
the cache files will always be regenerated. This effectively turns off
|
|
caching. $force_compile is usually for debugging purposes only, a more
|
|
efficient way of disabling caching is to set <link
|
|
linkend="variable.caching">$caching</link> = false (or 0.)
|
|
</para>
|
|
<para>
|
|
The <link linkend="api.is.cached">is_cached()</link> function
|
|
can be used to test if a template has a valid cache or not. If you have a
|
|
cached template that requires something like a database fetch, you can use
|
|
this to skip that process.
|
|
</para>
|
|
<example>
|
|
<title>using is_cached()</title>
|
|
<programlisting>
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
|
|
if(!$smarty->is_cached('index.tpl')) {
|
|
// No cache available, do variable assignments here.
|
|
$contents = get_database_contents();
|
|
$smarty->assign($contents);
|
|
}
|
|
|
|
$smarty->display('index.tpl');</programlisting>
|
|
</example>
|
|
<para>
|
|
You can keep parts of a page dynamic with the <link
|
|
linkend="language.function.insert">insert</link> template function. Let's
|
|
say the whole page can be cached except for a banner that is displayed down
|
|
the right side of the page. By using an insert function for the banner, you
|
|
can keep this element dynamic within the cached content. See the
|
|
documentation on <link linkend="language.function.insert">insert</link> for
|
|
details and examples.
|
|
</para>
|
|
<para>
|
|
You can clear all the cache files with the <link
|
|
linkend="api.clear.all.cache">clear_all_cache()</link> function, or
|
|
individual cache files (or groups) with the <link
|
|
linkend="api.clear.cache">clear_cache()</link> function.
|
|
</para>
|
|
<example>
|
|
<title>clearing the cache</title>
|
|
<programlisting>
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
|
|
// clear out all cache files
|
|
$smarty->clear_all_cache();
|
|
|
|
// clear only cache for index.tpl
|
|
$smarty->clear_cache('index.tpl');
|
|
|
|
$smarty->display('index.tpl');</programlisting>
|
|
</example>
|
|
</sect1>
|
|
<sect1 id="caching.multiple.caches">
|
|
<title>Multiple Caches Per Page</title>
|
|
<para>
|
|
You can have multiple cache files for a single call to display() or
|
|
fetch(). Let's say that a call to display('index.tpl') may have several
|
|
different output contents depending on some condition, and you want
|
|
separate caches for each one. You can do this by passing a cache_id as the
|
|
second parameter to the function call.
|
|
</para>
|
|
<example>
|
|
<title>passing a cache_id to display()</title>
|
|
<programlisting>
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
|
|
$my_cache_id = $_GET['article_id'];
|
|
|
|
$smarty->display('index.tpl',$my_cache_id);</programlisting>
|
|
</example>
|
|
<para>
|
|
Above, we are passing the variable $my_cache_id to display() as the
|
|
cache_id. For each unique value of $my_cache_id, a separate cache will be
|
|
generated for index.tpl. In this example, "article_id" was passed in the
|
|
URL and is used as the cache_id.
|
|
</para>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
Be very cautious when passing values from a client (web browser) into
|
|
Smarty (or any PHP application.) Although the above example of using the
|
|
article_id from the URL looks handy, it could have bad consequences. The
|
|
cache_id is used to create a directory on the file system, so if the user
|
|
decided to pass an extremely large value for article_id, or write a script
|
|
that sends random article_ids at a rapid pace, this could possibly cause
|
|
problems at the server level. Be sure to sanitize any data passed in before
|
|
using it. In this instance, maybe you know the article_id has a length of
|
|
10 characters and is made up of alpha-numerics only, and must be a valid
|
|
article_id in the database. Check for this!
|
|
</para>
|
|
</note>
|
|
<para>
|
|
Be sure to pass the same cache_id as the
|
|
second parameter to <link linkend="api.is.cached">is_cached()</link> and
|
|
<link linkend="api.clear.cache">clear_cache()</link>.
|
|
</para>
|
|
<example>
|
|
<title>passing a cache_id to is_cached()</title>
|
|
<programlisting>
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
|
|
$my_cache_id = $_GET['article_id'];
|
|
|
|
if(!$smarty->is_cached('index.tpl',$my_cache_id)) {
|
|
// No cache available, do variable assignments here.
|
|
$contents = get_database_contents();
|
|
$smarty->assign($contents);
|
|
}
|
|
|
|
$smarty->display('index.tpl',$my_cache_id);</programlisting>
|
|
</example>
|
|
<para>
|
|
You can clear all caches for a particular cache_id by passing null as the
|
|
first parameter to clear_cache().
|
|
</para>
|
|
<example>
|
|
<title>clearing all caches for a particular cache_id</title>
|
|
<programlisting>
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
|
|
// clear all caches with "sports" as the cache_id
|
|
$smarty->clear_cache(null,"sports");
|
|
|
|
$smarty->display('index.tpl',"sports");</programlisting>
|
|
</example>
|
|
<para>
|
|
In this manner, you can "group" your caches together by giving them the
|
|
same cache_id.
|
|
</para>
|
|
</sect1>
|
|
<sect1 id="caching.groups">
|
|
<title>Cache Groups</title>
|
|
<para>
|
|
You can do more elaborate grouping by setting up cache_id groups. This is
|
|
accomplished by separating each sub-group with a vertical bar "|" in the
|
|
cache_id value. You can have as many sub-groups as you like.
|
|
</para>
|
|
<example>
|
|
<title>cache_id groups</title>
|
|
<programlisting>
|
|
require('Smarty.class.php');
|
|
$smarty = new Smarty;
|
|
|
|
$smarty->caching = true;
|
|
|
|
// clear all caches with "sports|basketball" as the first two cache_id groups
|
|
$smarty->clear_cache(null,"sports|basketball");
|
|
|
|
// clear all caches with "sports" as the first cache_id group. This would
|
|
// include "sports|basketball", or "sports|(anything)|(anything)|(anything)|..."
|
|
$smarty->clear_cache(null,"sports");
|
|
|
|
$smarty->display('index.tpl',"sports|basketball");</programlisting>
|
|
</example>
|
|
<note>
|
|
<title>Technical Note</title>
|
|
<para>
|
|
The cache grouping does NOT use the path to the template as any part of the
|
|
cache_id. For example, if you have display('themes/blue/index.tpl'), you
|
|
cannot clear the cache for everything under the "themes/blue" directory. If
|
|
you want to do that, you must group them in the cache_id, such as
|
|
display('themes/blue/index.tpl','themes|blue'); Then you can clear the
|
|
caches for the blue theme with clear_cache(null,'themes|blue');
|
|
</para>
|
|
</note>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="advanced.features">
|
|
<title>Advanced Features</title>
|
|
<sect1 id="advanced.features.prefilters">
|
|
<title>Prefilters</title>
|
|
<para>
|
|
Template prefilters are PHP functions that your templates are ran through
|
|
before they are compiled. This is good for preprocessing your templates
|
|
to remove unwanted comments, keeping an eye on what people are putting
|
|
in their templates, etc. Prefilters can be either
|
|
<link linkend="api.register.prefilter">registered</link> or loaded from
|
|
the plugins directory by using
|
|
<link linkend="api.load.filter">load_filter()</link> function or by
|
|
setting
|
|
<link linkend="variable.autoload.filters">$autoload_filters</link> variable.
|
|
Smarty will pass the template source code as the first argument, and
|
|
expect the function to return the resulting template source code.
|
|
</para>
|
|
<example>
|
|
<title>using a template prefilter</title>
|
|
<programlisting>
|
|
<?php
|
|
// put this in your application
|
|
function remove_dw_comments($tpl_source, &$smarty)
|
|
{
|
|
return preg_replace("/<!--#.*-->/U","",$tpl_source);
|
|
}
|
|
|
|
// register the prefilter
|
|
$smarty->register_prefilter("remove_dw_comments");
|
|
$smarty->display("index.tpl");
|
|
?>
|
|
|
|
{* Smarty template index.tpl *}
|
|
<!--# this line will get removed by the prefilter --></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="advanced.features.postfilters">
|
|
<title>Postfilters</title>
|
|
<para>
|
|
Template postfilters are PHP functions that your templates are ran through
|
|
after they are compiled. Postfilters can be either
|
|
<link linkend="api.register.postfilter">registered</link> or loaded
|
|
from the plugins directory by using
|
|
<link linkend="api.load.filter">load_filter()</link> function or by
|
|
setting
|
|
<link linkend="variable.autoload.filters">$autoload_filters</link>
|
|
variable. Smarty will pass the compiled template code as the first
|
|
argument, and expect the function to return the result of the
|
|
processing.
|
|
</para>
|
|
<example>
|
|
<title>using a template postfilter</title>
|
|
<programlisting>
|
|
<?php
|
|
// put this in your application
|
|
function add_header_comment($tpl_source, &$smarty)
|
|
{
|
|
return "<?php echo \"<!-- Created by Smarty! -->\n\" ?>\n".$tpl_source;
|
|
}
|
|
|
|
// register the postfilter
|
|
$smarty->register_postfilter("add_header_comment");
|
|
$smarty->display("index.tpl");
|
|
?>
|
|
|
|
{* compiled Smarty template index.tpl *}
|
|
<!-- Created by Smarty! -->
|
|
{* rest of template content... *}</programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="advanced.features.outputfilters">
|
|
<title>Output Filters</title>
|
|
<para>
|
|
When the template is invoked via display() or fetch(), its output can be
|
|
sent through one or more output filters. This differs from postfilters
|
|
because postfilters operate on compiled templates before they are saved to
|
|
the disk, and output filters operate on the template output when it is
|
|
executed.
|
|
</para>
|
|
|
|
<para>
|
|
Output filters can be either
|
|
<link linkend="api.register.outputfilter">registered</link> or loaded
|
|
from the plugins directory by using
|
|
<link linkend="api.load.filter">load_filter()</link> function or by
|
|
setting
|
|
<link linkend="variable.autoload.filters">$autoload_filters</link>
|
|
variable. Smarty will pass the template output as the first argument,
|
|
and expect the function to return the result of the processing.
|
|
</para>
|
|
<example>
|
|
<title>using a template outputfilter</title>
|
|
<programlisting>
|
|
<?php
|
|
// put this in your application
|
|
function protect_email($tpl_output, &$smarty)
|
|
{
|
|
$tpl_output =
|
|
preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
|
|
'$1%40$2', $tpl_output);
|
|
return $tpl_output;
|
|
}
|
|
|
|
// register the outputfilter
|
|
$smarty->register_outputfilter("protect_email");
|
|
$smarty->display("index.tpl");
|
|
|
|
// now any occurrence of an email address in the template output will have
|
|
// a simple protection against spambots
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="section.template.cache.handler.func">
|
|
<title>Cache Handler Function</title>
|
|
<para>
|
|
As an alternative to using the default file-based caching mechanism, you
|
|
can specify a custom cache handling function that will be used to read,
|
|
write and clear cached files.
|
|
</para>
|
|
<para>
|
|
Create a function in your application that Smarty will use as a
|
|
cache handler. Set the name of it in the
|
|
<link linkend="variable.cache.handler.func">$cache_handler_func</link>
|
|
class variable. Smarty will now use this to handle cached data. The
|
|
first argument is the action, which will be one of 'read', 'write' and
|
|
'clear'. The second parameter is the Smarty object. The third parameter
|
|
is the cached content. Upon a write, Smarty passes the cached content
|
|
in these parameters. Upon a 'read', Smarty expects your function to
|
|
accept this parameter by reference and populate it with the cached
|
|
data. Upon a 'clear', pass a dummy variable here since it is not used.
|
|
The fourth parameter is the name of the template file (needed for
|
|
read/write), the fifth parameter is the cache_id (optional), and the
|
|
sixth is the compile_id (optional).
|
|
</para>
|
|
<example>
|
|
<title>example using MySQL as a cache source</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
|
|
example usage:
|
|
|
|
include('Smarty.class.php');
|
|
include('mysql_cache_handler.php');
|
|
|
|
$smarty = new Smarty;
|
|
$smarty->cache_handler_func = 'mysql_cache_handler';
|
|
|
|
$smarty->display('index.tpl');
|
|
|
|
|
|
mysql database is expected in this format:
|
|
|
|
create database SMARTY_CACHE;
|
|
|
|
create table CACHE_PAGES(
|
|
CacheID char(32) PRIMARY KEY,
|
|
CacheContents MEDIUMTEXT NOT NULL
|
|
);
|
|
|
|
*/
|
|
|
|
function mysql_cache_handler($action, &$smarty_obj, &$cache_content, $tpl_file=null, $cache_id=null, $compile_id=null)
|
|
{
|
|
// set db host, user and pass here
|
|
$db_host = 'localhost';
|
|
$db_user = 'myuser';
|
|
$db_pass = 'mypass';
|
|
$db_name = 'SMARTY_CACHE';
|
|
$use_gzip = false;
|
|
|
|
// create unique cache id
|
|
$CacheID = md5($tpl_file.$cache_id.$compile_id);
|
|
|
|
if(! $link = mysql_pconnect($db_host, $db_user, $db_pass)) {
|
|
$smarty_obj->_trigger_error_msg("cache_handler: could not connect to database");
|
|
return false;
|
|
}
|
|
mysql_select_db($db_name);
|
|
|
|
switch ($action) {
|
|
case 'read':
|
|
// save cache to database
|
|
$results = mysql_query("select CacheContents from CACHE_PAGES where CacheID='$CacheID'");
|
|
if(!$results) {
|
|
$smarty_obj->_trigger_error_msg("cache_handler: query failed.");
|
|
}
|
|
$row = mysql_fetch_array($results,MYSQL_ASSOC);
|
|
|
|
if($use_gzip && function_exists("gzuncompress")) {
|
|
$cache_contents = gzuncompress($row["CacheContents"]);
|
|
} else {
|
|
$cache_contents = $row["CacheContents"];
|
|
}
|
|
$return = $results;
|
|
break;
|
|
case 'write':
|
|
// save cache to database
|
|
|
|
if($use_gzip && function_exists("gzcompress")) {
|
|
// compress the contents for storage efficiency
|
|
$contents = gzcompress($cache_content);
|
|
} else {
|
|
$contents = $cache_content;
|
|
}
|
|
$results = mysql_query("replace into CACHE_PAGES values(
|
|
'$CacheID',
|
|
'".addslashes($contents)."')
|
|
");
|
|
if(!$results) {
|
|
$smarty_obj->_trigger_error_msg("cache_handler: query failed.");
|
|
}
|
|
$return = $results;
|
|
break;
|
|
case 'clear':
|
|
// clear cache info
|
|
if(empty($cache_id) && empty($compile_id) && empty($tpl_file)) {
|
|
// clear them all
|
|
$results = mysql_query("delete from CACHE_PAGES");
|
|
} else {
|
|
$results = mysql_query("delete from CACHE_PAGES where CacheID='$CacheID'");
|
|
}
|
|
if(!$results) {
|
|
$smarty_obj->_trigger_error_msg("cache_handler: query failed.");
|
|
}
|
|
$return = $results;
|
|
break;
|
|
default:
|
|
// error, unknown action
|
|
$smarty_obj->_trigger_error_msg("cache_handler: unknown action \"$action\"");
|
|
$return = false;
|
|
break;
|
|
}
|
|
mysql_close($link);
|
|
return $return;
|
|
|
|
}
|
|
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="template.resources">
|
|
<title>Resources</title>
|
|
<para>
|
|
The templates may come from a variety of sources. When you display or
|
|
fetch a template, or when you include a template from within another
|
|
template, you supply a resource type, followed by the appropriate path
|
|
and template name.
|
|
</para>
|
|
<sect2 id="templates.from.template.dir">
|
|
<title>Templates from $template_dir</title>
|
|
<para>
|
|
Templates from the $template_dir do not require a template
|
|
resource, although you can use the file: resource for consistancy.
|
|
Just supply the path to the template you want to use relative to
|
|
the $template_dir root directory.
|
|
</para>
|
|
<example>
|
|
<title>using templates from $template_dir</title>
|
|
<programlisting>
|
|
// from PHP script
|
|
$smarty->display("index.tpl");
|
|
$smarty->display("admin/menu.tpl");
|
|
$smarty->display("file:admin/menu.tpl"); // same as one above
|
|
|
|
{* from within Smarty template *}
|
|
{include file="index.tpl"}
|
|
{include file="file:index.tpl"} {* same as one above *}</programlisting>
|
|
</example>
|
|
</sect2>
|
|
<sect2 id="templates.from.any.dir">
|
|
<title>Templates from any directory</title>
|
|
<para>
|
|
Templates outside of the $template_dir require the file: template
|
|
resource type, followed by the absolute path and name of the
|
|
template.
|
|
</para>
|
|
<example>
|
|
<title>using templates from any directory</title>
|
|
<programlisting>
|
|
// from PHP script
|
|
$smarty->display("file:/export/templates/index.tpl");
|
|
$smarty->display("file:/path/to/my/templates/menu.tpl");
|
|
|
|
{* from within Smarty template *}
|
|
{include file="file:/usr/local/share/templates/navigation.tpl"}</programlisting>
|
|
</example>
|
|
|
|
<sect3>
|
|
<title>Windows Filepaths</title>
|
|
<para>
|
|
If you are using a Windows machine, filepaths usually include a
|
|
drive letter (C:) at the beginning of the pathname. Be sure to use
|
|
"file:" in the path to avoid namespace conflicts and get the
|
|
desired results.
|
|
</para>
|
|
<example>
|
|
<title>using templates from windows file paths</title>
|
|
<programlisting>
|
|
// from PHP script
|
|
$smarty->display("file:C:/export/templates/index.tpl");
|
|
$smarty->display("file:F:/path/to/my/templates/menu.tpl");
|
|
|
|
{* from within Smarty template *}
|
|
{include file="file:D:/usr/local/share/templates/navigation.tpl"}</programlisting>
|
|
</example>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
<sect2 id="templates.from.elsewhere">
|
|
<title>Templates from other sources</title>
|
|
<para>
|
|
You can retrieve templates using whatever possible source you can
|
|
access with PHP: databases, sockets, LDAP, and so on. You do this
|
|
by writing resource plugin functions and registering them with
|
|
Smarty.
|
|
</para>
|
|
|
|
<para>
|
|
See <link linkend="plugins.resources">resource plugins</link>
|
|
section for more information on the functions you are supposed
|
|
to provide.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Note that you cannot override the built-in
|
|
<literal>file</literal> resource, but you can provide a resource
|
|
that fetches templates from the file system in some other way by
|
|
registering under another resource name.
|
|
</para>
|
|
</note>
|
|
<example>
|
|
<title>using custom resources</title>
|
|
<programlisting>
|
|
// from PHP script
|
|
|
|
// put these function somewhere in your application
|
|
function db_get_template ($tpl_name, &tpl_source, &$smarty_obj)
|
|
{
|
|
// do database call here to fetch your template,
|
|
// populating $tpl_source
|
|
$sql = new SQL;
|
|
$sql->query("select tpl_source
|
|
from my_table
|
|
where tpl_name='$tpl_name'");
|
|
if ($sql->num_rows) {
|
|
$tpl_source = $sql->record['tpl_source'];
|
|
return true;
|
|
} else {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
function db_get_timestamp($tpl_name, &$tpl_timestamp, &$smarty_obj)
|
|
{
|
|
// do database call here to populate $tpl_timestamp.
|
|
$sql = new SQL;
|
|
$sql->query("select tpl_timestamp
|
|
from my_table
|
|
where tpl_name='$tpl_name'");
|
|
if ($sql->num_rows) {
|
|
$tpl_timestamp = $sql->record['tpl_timestamp'];
|
|
return true;
|
|
} else {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
function db_get_secure($tpl_name, &$smarty_obj)
|
|
{
|
|
// assume all templates are secure
|
|
return true;
|
|
}
|
|
|
|
function db_get_trusted($tpl_name, &$smarty_obj)
|
|
{
|
|
// not used for templates
|
|
}
|
|
|
|
// register the resource name "db"
|
|
$smarty->register_resource("db", array("db_get_template",
|
|
"db_get_timestamp",
|
|
"db_get_secure",
|
|
"db_get_trusted"));
|
|
|
|
// using resource from php script
|
|
$smarty->display("db:index.tpl");
|
|
|
|
{* using resource from within Smarty template *}
|
|
{include file="db:/extras/navigation.tpl"}</programlisting>
|
|
</example>
|
|
</sect2>
|
|
|
|
<sect2 id="default.template.handler.function">
|
|
<title>Default template handler function</title>
|
|
<para>
|
|
You can specify a function that is used to retrieve template
|
|
contents in the event the template cannot be retrieved from its
|
|
resource. One use of this is to create templates that do not exist
|
|
on-the-fly.
|
|
</para>
|
|
<example>
|
|
<title>using the default template handler function</title>
|
|
<programlisting>
|
|
<?php
|
|
// put this function somewhere in your application
|
|
|
|
function make_template ($resource_type, $resource_name, &$template_source, &$template_timestamp, &$smarty_obj)
|
|
{
|
|
if( $resource_type == 'file' ) {
|
|
if ( ! is_readable ( $resource_name )) {
|
|
// create the template file, return contents.
|
|
$template_source = "This is a new template.";
|
|
$template_timestamp = time();
|
|
$smarty_obj->_write_file($resource_name,$template_source);
|
|
return true;
|
|
}
|
|
} else {
|
|
// not a file
|
|
return false;
|
|
}
|
|
}
|
|
|
|
// set the default handler
|
|
$smarty->default_template_handler_func = 'make_template';
|
|
?></programlisting>
|
|
</example>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<chapter id="plugins">
|
|
<title>Extending Smarty With Plugins</title>
|
|
<para>
|
|
Version 2.0 introduced the plugin architecture that is used
|
|
for almost all the customizable functionality of Smarty. This includes:
|
|
<itemizedlist spacing=compact>
|
|
<listitem><simpara>functions</simpara></listitem>
|
|
<listitem><simpara>modifiers</simpara></listitem>
|
|
<listitem><simpara>block functions</simpara></listitem>
|
|
<listitem><simpara>compiler functions</simpara></listitem>
|
|
<listitem><simpara>prefilters</simpara></listitem>
|
|
<listitem><simpara>postfilters</simpara></listitem>
|
|
<listitem><simpara>outputfilters</simpara></listitem>
|
|
<listitem><simpara>resources</simpara></listitem>
|
|
<listitem><simpara>inserts</simpara></listitem>
|
|
</itemizedlist>
|
|
With the exception of resources, backwards compatibility with the old
|
|
way of registering handler functions via register_* API is preserved. If
|
|
you did not use the API but instead modified the class variables
|
|
<literal>$custom_funcs</literal>, <literal>$custom_mods</literal>, and
|
|
other ones directly, then you will need to adjust your scripts to either
|
|
use the API or convert your custom functionality into plugins.
|
|
</para>
|
|
|
|
<sect1>
|
|
<title>How Plugins Work</title>
|
|
<para>
|
|
Plugins are always loaded on demand. Only the specific modifiers,
|
|
functions, resources, etc invoked in the templates scripts will be
|
|
loaded. Moreover, each plugin is loaded only once, even if you have
|
|
several different instances of Smarty running within the same request.
|
|
</para>
|
|
<para>
|
|
Pre/postfilters and output filters are a bit of a special case. Since
|
|
they are not mentioned in the templates, they must be registered or
|
|
loaded explicitly via API functions before the template is processed.
|
|
The order in which multiple filters of the same type are executed
|
|
depends on the order in which they are registered or loaded.
|
|
</para>
|
|
<para>
|
|
There is only one plugins directory (for performance reasons). To
|
|
install a plugin, simply place it in the directory and Smarty will use
|
|
it automatically.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.naming.conventions">
|
|
<title>Naming Conventions</title>
|
|
<para>
|
|
Plugin files and functions must follow a very specific naming
|
|
convention in order to be located by Smarty.
|
|
</para>
|
|
<para>
|
|
The plugin files must be named as follows:
|
|
<blockquote>
|
|
<para>
|
|
<filename>
|
|
<replaceable>type</replaceable>.<replaceable>name</replaceable>.php
|
|
</filename>
|
|
</para>
|
|
</blockquote>
|
|
</para>
|
|
<para>
|
|
Where <literal>type</literal> is one of these plugin types:
|
|
<itemizedlist spacing=compact>
|
|
<listitem><simpara>function</simpara></listitem>
|
|
<listitem><simpara>modifier</simpara></listitem>
|
|
<listitem><simpara>block</simpara></listitem>
|
|
<listitem><simpara>compiler</simpara></listitem>
|
|
<listitem><simpara>prefilter</simpara></listitem>
|
|
<listitem><simpara>postfilter</simpara></listitem>
|
|
<listitem><simpara>outputfilter</simpara></listitem>
|
|
<listitem><simpara>resource</simpara></listitem>
|
|
<listitem><simpara>insert</simpara></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
And <literal>name</literal> should be a valid identifier (letters,
|
|
numbers, and underscores only).
|
|
</para>
|
|
<para>
|
|
Some examples: <literal>function.html_select_date.php</literal>,
|
|
<literal>resource.db.php</literal>,
|
|
<literal>modifier.spacify.php</literal>.
|
|
</para>
|
|
<para>
|
|
The plugin functions inside the plugin files must be named as follows:
|
|
<blockquote>
|
|
<para>
|
|
<function>smarty_<replaceable>type</replaceable>_<replaceable>name</replaceable></function>
|
|
</para>
|
|
</blockquote>
|
|
</para>
|
|
<para>
|
|
The meanings of <literal>type</literal> and <literal>name</literal> are
|
|
the same as before.
|
|
</para>
|
|
<para>
|
|
Smarty will output appropriate error messages if the plugin file it
|
|
needs is not found, or if the file or the plugin function are named
|
|
improperly.
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.writing">
|
|
<title>Writing Plugins</title>
|
|
<para>
|
|
Plugins can be either loaded by Smarty automatically from the
|
|
filesystem or they can be registered at runtime via one of the
|
|
register_* API functions. They can also be unregistered by using
|
|
unregister_* API functions.
|
|
</para>
|
|
<para>
|
|
For the plugins that are registered at runtime, the name of the plugin
|
|
function(s) does not have to follow the naming convention.
|
|
</para>
|
|
<para>
|
|
If a plugin depends on some functionality provided by another plugin
|
|
(as is the case with some plugins bundled with Smarty), then the proper
|
|
way to load the needed plugin is this:
|
|
</para>
|
|
<programlisting>
|
|
require_once SMARTY_DIR . 'plugins/function.html_options.php';</programlisting>
|
|
<para>
|
|
As a general rule, Smarty object is always passed to the plugins as the last
|
|
parameter (except for modifiers).
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.functions"><title>Template Functions</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>smarty_function_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>array <parameter>$params</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
All attributes passed to template functions from the template are
|
|
contained in the <parameter>$params</parameter> as an associative
|
|
array. Either access those values directly, e.g.
|
|
<varname>$params['start']</varname> or use
|
|
<varname>extract($params)</varname> to import them into the symbol
|
|
table.
|
|
</para>
|
|
<para>
|
|
The output of the function will be substituted in place of the
|
|
function tag in the template (<function>fetch</function> function, for
|
|
example). Alternatively, the function can simply perform some other
|
|
task without any output (<function>assign</function> function).
|
|
</para>
|
|
<para>
|
|
If the function needs to assign some variables to the template or use
|
|
some other Smarty-provided functionality, it can use the supplied
|
|
<parameter>$smarty</parameter> object to do so.
|
|
</para>
|
|
<para>
|
|
See also:
|
|
<link linkend="api.register.function">register_function()</link>,
|
|
<link linkend="api.unregister.function">unregister_function()</link>.
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>function plugin with output</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: function.eightball.php
|
|
* Type: function
|
|
* Name: eightball
|
|
* Purpose: outputs a random magic answer
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_function_eightball($params, &$smarty)
|
|
{
|
|
$answers = array('Yes',
|
|
'No',
|
|
'No way',
|
|
'Outlook not so good',
|
|
'Ask again soon',
|
|
'Maybe in your reality');
|
|
|
|
$result = array_rand($answers);
|
|
echo $answers[$result];
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</para>
|
|
<para>
|
|
which can be used in the template as:
|
|
</para>
|
|
<programlisting>
|
|
Question: Will we ever have time travel?
|
|
Answer: {eightball}.</programlisting>
|
|
<para>
|
|
<example>
|
|
<title>function plugin without output</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: function.assign.php
|
|
* Type: function
|
|
* Name: assign
|
|
* Purpose: assign a value to a template variable
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_function_assign($params, &$smarty)
|
|
{
|
|
extract($params);
|
|
|
|
if (empty($var)) {
|
|
$smarty->trigger_error("assign: missing 'var' parameter");
|
|
return;
|
|
}
|
|
|
|
if (!in_array('value', array_keys($params))) {
|
|
$smarty->trigger_error("assign: missing 'value' parameter");
|
|
return;
|
|
}
|
|
|
|
$smarty->assign($var, $value);
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</para>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.modifiers"><title>Modifiers</title>
|
|
<para>
|
|
Modifiers are little functions that are applied to a variable in the
|
|
template before it is displayed or used in some other context.
|
|
Modifiers can be chained together.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>mixed <function>smarty_modifier_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>mixed <parameter>$value</parameter></paramdef>
|
|
<paramdef>[mixed <parameter>$param1</parameter>, ...]</paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The first parameter to the modifier plugin is the value on which
|
|
the modifier is supposed to operate. The rest of the parameters can be
|
|
optional, depending on what kind of operation is supposed to be
|
|
performed.
|
|
</para>
|
|
<para>
|
|
The modifier has to return the result of its processing.
|
|
</para>
|
|
<para>
|
|
See also
|
|
<link linkend="api.register.modifier">register_modifier()</link>,
|
|
<link linkend="api.unregister.modifier">unregister_modifier()</link>.
|
|
</para>
|
|
<example>
|
|
<title>simple modifier plugin</title>
|
|
<para>
|
|
This plugin basically aliases one of the built-in PHP functions. It
|
|
does not have any additional parameters.
|
|
</para>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: modifier.capitalize.php
|
|
* Type: modifier
|
|
* Name: capitalize
|
|
* Purpose: capitalize words in the string
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_modifier_capitalize($string)
|
|
{
|
|
return ucwords($string);
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
<para></para>
|
|
<example>
|
|
<title>more complex modifier plugin</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: modifier.truncate.php
|
|
* Type: modifier
|
|
* Name: truncate
|
|
* Purpose: Truncate a string to a certain length if necessary,
|
|
* optionally splitting in the middle of a word, and
|
|
* appending the $etc string.
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_modifier_truncate($string, $length = 80, $etc = '...',
|
|
$break_words = false)
|
|
{
|
|
if ($length == 0)
|
|
return '';
|
|
|
|
if (strlen($string) > $length) {
|
|
$length -= strlen($etc);
|
|
$fragment = substr($string, 0, $length+1);
|
|
if ($break_words)
|
|
$fragment = substr($fragment, 0, -1);
|
|
else
|
|
$fragment = preg_replace('/\s+(\S+)?$/', '', $fragment);
|
|
return $fragment.$etc;
|
|
} else
|
|
return $string;
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.block.functions"><title>Block Functions</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>smarty_function_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>array <parameter>$params</parameter></paramdef>
|
|
<paramdef>mixed <parameter>$content</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Block functions are functions of the form: {func} .. {/func}. In other
|
|
words, they enclose a template block and operate on the contents of
|
|
this block. Block functions take precedence over custom functions of
|
|
the same name, that is, you cannot have both custom function {func} and
|
|
block function {func} .. {/func}.
|
|
</para>
|
|
<para>
|
|
Your function implementation is called twice by Smarty:
|
|
once for the opening tag, and once for the closing tag.
|
|
</para>
|
|
<para>
|
|
Only the opening tag of the block function may have attributes. All
|
|
attributes passed to template functions from the template are contained
|
|
in the <parameter>$params</parameter> as an associative array. You can
|
|
either access those values directly, e.g.
|
|
<varname>$params['start']</varname> or use
|
|
<varname>extract($params)</varname> to import them into the symbol
|
|
table. The opening tag attributes are also accessible to your function
|
|
when processing the closing tag.
|
|
</para>
|
|
<para>
|
|
The value of <parameter>$content</parameter> variable depends on
|
|
whether your function is called for the opening or closing tag. In case
|
|
of the opening tag, it will be <literal>null</literal>, and in case of
|
|
the closing tag it will be the contents of the template block.
|
|
Note that the template block will have already been processed by
|
|
Smarty, so all you will receive is the template output, not the
|
|
template source.
|
|
</para>
|
|
<para>
|
|
If you have nested block functions, it's possible to find out what the
|
|
parent block function is by accessing
|
|
<varname>$smarty->_tag_stack</varname> variable. Just do a var_dump()
|
|
on it and the structure should be apparent.
|
|
</para>
|
|
<para>
|
|
See also:
|
|
<link linkend="api.register.block">register_block()</link>,
|
|
<link linkend="api.unregister.block">unregister_block()</link>.
|
|
</para>
|
|
<example>
|
|
<title>block function</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: block.translate.php
|
|
* Type: block
|
|
* Name: translate
|
|
* Purpose: translate a block of text
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_block_translate($params, $content, &$smarty)
|
|
{
|
|
if ($content) {
|
|
$lang = $params['lang'];
|
|
// do some intelligent translation thing here with $content
|
|
echo $translation;
|
|
}
|
|
}</programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.compiler.functions"><title>Compiler Functions</title>
|
|
<para>
|
|
Compiler functions are called only during compilation of the template.
|
|
They are useful for injecting PHP code or time-sensitive static
|
|
content into the template. If there is both a compiler function and a
|
|
custom function registered under the same name, the compiler function
|
|
has precedence.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>mixed <function>smarty_compiler_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>string <parameter>$tag_arg</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The compiler function is passed two parameters: the tag argument
|
|
string - basically, everything from the function name until the ending
|
|
delimiter, and the Smarty object. It's supposed to return the PHP code
|
|
to be injected into the compiled template.
|
|
</para>
|
|
<para>
|
|
See also
|
|
<link linkend="api.register.compiler.function">register_compiler_function()</link>,
|
|
<link linkend="api.unregister.compiler.function">unregister_compiler_function()</link>.
|
|
</para>
|
|
<example>
|
|
<title>simple compiler function</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: compiler.tplheader.php
|
|
* Type: compiler
|
|
* Name: tplheader
|
|
* Purpose: Output header containing the source file name and
|
|
* the time it was compiled.
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_compiler_tplheader($tag_arg, &$smarty)
|
|
{
|
|
return "\necho '" . $smarty->_current_file . " compiled at " . date('Y-m-d H:M'). "';";
|
|
}
|
|
?></programlisting>
|
|
<para>
|
|
This function can be called from the template as:
|
|
</para>
|
|
<programlisting>
|
|
{* this function gets executed at compile time only *}
|
|
{tplheader}</programlisting>
|
|
<para>
|
|
The resulting PHP code in the compiled template would be something like this:
|
|
</para>
|
|
<programlisting>
|
|
<php
|
|
echo 'index.tpl compiled at 2002-02-20 20:02';
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.prefilters.postfilters">
|
|
<title>Prefilters/Postfilters</title>
|
|
<para>
|
|
Prefilter and postfilter plugins are very similar in concept; where
|
|
they differ is in the execution -- more precisely the time of their
|
|
execution.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>smarty_prefilter_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>string <parameter>$source</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Prefilters are used to process the source of the template immediately
|
|
before compilation. The first parameter to the prefilter function is
|
|
the template source, possibly modified by some other prefilters. The
|
|
plugin is supposed to return the modified source. Note that this
|
|
source is not saved anywhere, it is only used for compilation.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>smarty_postfilter_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>string <parameter>$compiled</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
Postfilters are used to process the compiled output of the template
|
|
(the PHP code) immediately after the compilation is done but before the
|
|
compiled template is saved to the filesystem. The first parameter to
|
|
the postfilter function is the compiled template code, possibly
|
|
modified by other postfilters. The plugin is supposed to return the
|
|
modified version of this code.
|
|
</para>
|
|
<example>
|
|
<title>prefilter plugin</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: prefilter.pre01.php
|
|
* Type: prefilter
|
|
* Name: pre01
|
|
* Purpose: Convert html tags to be lowercase.
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_prefilter_pre01($source, &$smarty)
|
|
{
|
|
return preg_replace('!<(\w+)[^>]+>!e', 'strtolower("$1")', $source);
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
<para></para>
|
|
<example>
|
|
<title>postfilter plugin</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: postfilter.post01.php
|
|
* Type: postfilter
|
|
* Name: post01
|
|
* Purpose: Output code that lists all current template vars.
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_postfilter_post01($compiled, &$smarty)
|
|
{
|
|
$compiled = "<pre>\n<?php print_r(\$this->get_template_vars()); ?>\n</pre>" . $compiled;
|
|
return $compiled;
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.outputfilters"><title>Output Filters</title>
|
|
<para>
|
|
Output filter plugins operate on a template's output, after the
|
|
template is loaded and executed, but before the output is displayed.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>smarty_outputfilter_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>string <parameter>$template_output</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The first parameter to the output filter function is the template
|
|
output that needs to be processed, and the second parameter is the
|
|
instance of Smarty invoking the plugin. The plugin is supposed to do
|
|
the processing and return the results.
|
|
</para>
|
|
<example>
|
|
<title>output filter plugin</title>
|
|
<programlisting>
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: outputfilter.protect_email.php
|
|
* Type: outputfilter
|
|
* Name: protect_email
|
|
* Purpose: Converts @ sign in email addresses to %40 as
|
|
* a simple protection against spambots
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_outputfilter_protect_email($output, &$smarty)
|
|
{
|
|
return preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
|
|
'$1%40$2', $output);
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.resources"><title>Resources</title>
|
|
<para>
|
|
Resource plugins are meant as a generic way of providing template
|
|
sources or PHP script components to Smarty. Some examples of resources:
|
|
databases, LDAP, shared memory, sockets, and so on.
|
|
</para>
|
|
|
|
<para>
|
|
There are a total of 4 functions that need to be registered for each
|
|
type of resource. Every function will receive the requested resource as
|
|
the first parameter and the Smarty object as the last parameter. The
|
|
rest of parameters depend on the function.
|
|
</para>
|
|
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_source</function></funcdef>
|
|
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
|
|
<paramdef>string <parameter>&$source</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_timestamp</function></funcdef>
|
|
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
|
|
<paramdef>int <parameter>&$timestamp</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_secure</function></funcdef>
|
|
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
<funcprototype>
|
|
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_trusted</function></funcdef>
|
|
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
|
|
<para>
|
|
The first function is supposed to retrieve the resource. Its second
|
|
parameter is a variable passed by reference where the result should be
|
|
stored. The function is supposed to return <literal>true</literal> if
|
|
it was able to successfully retrieve the resource and
|
|
<literal>false</literal> otherwise.
|
|
</para>
|
|
|
|
<para>
|
|
The second function is supposed to retrieve the last modification time
|
|
of the requested resource (as a UNIX timestamp). The second parameter
|
|
is a variable passed by reference where the timestamp should be stored.
|
|
The function is supposed to return <literal>true</literal> if the
|
|
timestamp could be succesfully determined, and <literal>false</literal>
|
|
otherwise.
|
|
</para>
|
|
|
|
<para>
|
|
The third function is supposed to return <literal>true</literal> or
|
|
<literal>false</literal>, depending on whether the requested resource
|
|
is secure or not. This function is used only for template resources but
|
|
should still be defined.
|
|
</para>
|
|
|
|
<para>
|
|
The fourth function is supposed to return <literal>true</literal> or
|
|
<literal>false</literal>, depending on whether the requested resource
|
|
is trusted or not. This function is used for only for PHP script
|
|
components requested by <command>include_php</command> tag or
|
|
<command>insert</command> tag with <structfield>src</structfield>
|
|
attribute. However, it should still be defined even for template
|
|
resources.
|
|
</para>
|
|
<para>
|
|
See also
|
|
<link linkend="api.register.resource">register_resource()</link>,
|
|
<link linkend="api.unregister.resource">unregister_resource()</link>.
|
|
</para>
|
|
<example>
|
|
<title>resource plugin</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: resource.db.php
|
|
* Type: resource
|
|
* Name: db
|
|
* Purpose: Fetches templates from a database
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_resource_db_source($tpl_name, &$tpl_source, &$smarty)
|
|
{
|
|
// do database call here to fetch your template,
|
|
// populating $tpl_source
|
|
$sql = new SQL;
|
|
$sql->query("select tpl_source
|
|
from my_table
|
|
where tpl_name='$tpl_name'");
|
|
if ($sql->num_rows) {
|
|
$tpl_source = $sql->record['tpl_source'];
|
|
return true;
|
|
} else {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
function smarty_resource_db_timestamp($tpl_name, &$tpl_timestamp, &$smarty)
|
|
{
|
|
// do database call here to populate $tpl_timestamp.
|
|
$sql = new SQL;
|
|
$sql->query("select tpl_timestamp
|
|
from my_table
|
|
where tpl_name='$tpl_name'");
|
|
if ($sql->num_rows) {
|
|
$tpl_timestamp = $sql->record['tpl_timestamp'];
|
|
return true;
|
|
} else {
|
|
return false;
|
|
}
|
|
}
|
|
|
|
function smarty_resource_db_secure($tpl_name, &$smarty)
|
|
{
|
|
// assume all templates are secure
|
|
return true;
|
|
}
|
|
|
|
function smarty_resource_db_trusted($tpl_name, &$smarty)
|
|
{
|
|
// not used for templates
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
|
|
<sect1 id="plugins.inserts"><title>Inserts</title>
|
|
<para>
|
|
Insert plugins are used to implement functions that are invoked by
|
|
<link linkend="language.function.insert"><command>insert</command></link>
|
|
tags in the template.
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>string <function>smarty_insert_<replaceable>name</replaceable></function></funcdef>
|
|
<paramdef>array <parameter>$params</parameter></paramdef>
|
|
<paramdef>object <parameter>&$smarty</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The first parameter to the function is an associative array of
|
|
attributes passed to the insert. Either access those values directly,
|
|
e.g. <varname>$params['start']</varname> or use
|
|
<varname>extract($params)</varname> to import them into the symbol
|
|
table.
|
|
</para>
|
|
<para>
|
|
The insert function is supposed to return the result which will be
|
|
substituted in place of the <command>insert</command> tag in the
|
|
template.
|
|
</para>
|
|
<example>
|
|
<title>insert plugin</title>
|
|
<programlisting>
|
|
<?php
|
|
/*
|
|
* Smarty plugin
|
|
* -------------------------------------------------------------
|
|
* File: insert.time.php
|
|
* Type: time
|
|
* Name: time
|
|
* Purpose: Inserts current date/time according to format
|
|
* -------------------------------------------------------------
|
|
*/
|
|
function smarty_insert_time($params, &$smarty)
|
|
{
|
|
if (empty($params['format'])) {
|
|
$smarty->trigger_error("insert time: missing 'format' parameter");
|
|
return;
|
|
}
|
|
|
|
$datetime = strftime($params['format']);
|
|
return $datetime;
|
|
}
|
|
?></programlisting>
|
|
</example>
|
|
</sect1>
|
|
</chapter>
|
|
</part>
|