mirror of
https://github.com/smarty-php/smarty.git
synced 2025-10-04 16:20:55 +02:00
2034 lines
70 KiB
Plaintext
2034 lines
70 KiB
Plaintext
<part id="smarty.for.programmers">
|
|
<title>Smarty For Programmers</title>
|
|
<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 mandatory 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. This was added to Smarty version
|
|
1.2.1.
|
|
</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 mandatory 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 mandatory 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 directory where Smarty will look for the plugins that
|
|
it needs. The directory must be relative to the directory where
|
|
Smarty itself is installed. Default is "plugins". There can be
|
|
only one plugins directory.
|
|
</para>
|
|
</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>
|
|
<para>
|
|
NOTE: This was added to Smarty 1.4.3.
|
|
</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.
|
|
</para>
|
|
<para>
|
|
NOTE: This was added to Smarty 1.4.3.
|
|
</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>
|
|
<para>
|
|
NOTE: This was added to Smarty 1.4.4.
|
|
</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.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. (added to Smarty 1.3.0)
|
|
</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 mandatory 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 this setting to work. You can also force the cache
|
|
to expire with <link
|
|
linkend="api.clear.all.cache">clear_all_cache</link>. A setting of -1
|
|
will force the cache to never expire. A setting of 0 will cause the
|
|
cache to always regenerate (which doesn't make much sense, you'd be
|
|
better off setting caching=false.) If $caching = 2, then the cache
|
|
expiration time is saved along with the template.
|
|
</para>
|
|
</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. (added to Smarty 1.5.2)
|
|
</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>
|
|
<para>
|
|
NOTE: Security features were added to Smarty 1.4.3.
|
|
</para>
|
|
</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>
|
|
</chapter>
|
|
|
|
<chapter id="api.functions">
|
|
<title>Methods</title>
|
|
<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.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.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. Array
|
|
functionality was added to Smarty 1.3.0.
|
|
</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.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.cache">
|
|
<title>clear_cache</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>clear_cache</function></funcdef>
|
|
<paramdef>string <parameter>template</parameter></paramdef>
|
|
<paramdef>string <parameter>cache id</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This clears the cache for the specified template. If you have
|
|
multiple caches for this template, you can clear a specific
|
|
cache by supplying the cache id as the second parameter. See the
|
|
<link linkend="features.caching">caching section</link> for more
|
|
information. This was added to Smarty 1.3.0.
|
|
</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.all.cache">
|
|
<title>clear_all_cache</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>clear_all_cache</function></funcdef>
|
|
<paramdef><parameter></parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
This clears the entire template cache. This was added to Smarty
|
|
1.3.0.
|
|
</para>
|
|
<example>
|
|
<title>clear_all_cache</title>
|
|
<programlisting>
|
|
// clear the entire cache
|
|
$smarty->clear_all_cache();</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.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.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.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.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.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.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>
|
|
<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.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.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.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.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.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.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. This function
|
|
was added to Smarty 2.0.
|
|
</para>
|
|
</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. This
|
|
was added to Smarty 1.3.0.
|
|
</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.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.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="features.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. This was added to Smarty 1.4.5.
|
|
</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="features.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. This was added to Smarty 1.4.5.
|
|
</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>
|
|
</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 are processed in the order they are
|
|
<link linkend="api.register.prefilter">registered</link> or loaded from
|
|
the <link linkend="plugins.prefilters.postfilters">plugin</link> directory.
|
|
Smarty will pass the template source code as the first argument, an
|
|
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)
|
|
{
|
|
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 are processed in the order they are
|
|
<link linkend="api.register.postfilter">registered</link> or loaded
|
|
from the <link linkend="plugins.prefilters.postfilters">plugin</link>
|
|
directory. Smarty will pass the compiled template code as the first
|
|
argument, an 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)
|
|
{
|
|
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="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>compiler functions</simpara></listitem>
|
|
<listitem><simpara>prefilters</simpara></listitem>
|
|
<listitem><simpara>postfilters</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 or PHP 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/post-filters are a bit of a special case. If a pre/post-filter
|
|
plugin is found in the plugins directory, it will always be loaded
|
|
because these filters are never explicitly mentioned in the template
|
|
language. This also means that the order in which multiple prefilters
|
|
or postfilters is executed depends on the way they are named
|
|
(basically, alphabetical order).
|
|
</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>compiler</simpara></listitem>
|
|
<listitem><simpara>prefilter</simpara></listitem>
|
|
<listitem><simpara>postfilter</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>
|
|
<note>
|
|
<para>
|
|
Note that pre/postfilters still have to be correctly named even though
|
|
the names are not used for anything except their order of execution.
|
|
</para>
|
|
</note>
|
|
</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.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.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>
|