smarty-php/smarty
1
0
Fork 0
mirror of https://github.com/smarty-php/smarty.git synced 2025-08-04 10:24:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

*** empty log message ***

Browse Source
This commit is contained in:
andrey
2002-02-22 17:32:17 +00:00
parent 27ba49c573
commit bcd97149d9
1 changed files with 912 additions and 836 deletions
Download Patch File Download Diff File Expand all files Collapse all files

438
docs.sgml
View File

@@ -1,23 +1,24 @@
<!dOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
<book id="index">
<bookinfo>
<bookinfo id="bookinfo">
<title>Smarty - the compiling PHP template engine</title>
<authorgroup id="authors">
<author>
<firstname>Monte</firstname><surname>Ohrt</surname>
<affiliation>
<address><email>monte@ispi.net</email></address>
</affiliation>
<firstname>Monte</firstname><surname>Ohrt &lt;monte@ispi.net&gt;</surname>
</author>
<author>
<firstname>Andrei</firstname><surname>Zmievski</surname>
<affiliation>
<address><email>andrei@php.net</email></address>
</affiliation>
<firstname>Andrei</firstname><surname>Zmievski &lt;andrei@php.net&gt;</surname>
</author>
<edition>Version 1.5.2</edition>
<copyright><year>2001</year><holder>ispi of Lincoln, Inc.</holder></copyright>
</authorgroup>
<edition>Version 2.0</edition>
<copyright>
<year>2001</year>
<year>2002</year>
<holder>ispi of Lincoln, Inc.</holder>
</copyright>
</bookinfo>
<chapter>
<chapter id="overview">
<title>Overview</title>
<para>
It is undoubtedly one of the most asked questions on the PHP mailing
@@ -64,7 +65,7 @@
and should not do. From this experience, we decided that the template
engine should be written in PHP as a class, for anyone to use as they
see fit. So we wrote an engine that did just that and
<emphasis>SmartTemplate</emphasis> came into existence (note: this
<productname>SmartTemplate</productname> came into existence (note: this
class was never submitted to the public). It was a class that did
almost everything we wanted: regular variable substitution, supported
including other templates, integration with config files, embedding PHP
@@ -85,7 +86,8 @@
syntax. So what if we combined the two strengths? Thus, Smarty was
born...
</para>
<sect1>
<sect1 id="what.is.smarty">
<title>What is Smarty?</title>
<para>
Smarty is a template engine for PHP. One of the unique aspects about
@@ -123,9 +125,11 @@
<listitem><para>Custom cache handling functions (new in 1.4.7)</para></listitem>
</itemizedlist>
</sect1>
<sect1>
<sect1 id="how.smarty.works">
<title>How Smarty works</title>
<sect2><title>Compiling</title>
<sect2 id="compiling"><title>Compiling</title>
<para>
Smarty compiles the templates into native PHP code on-the-fly. The actual
PHP scripts that are generated are created implicitly, so theoretically you
@@ -134,14 +138,15 @@
discussed later in this document.
</para>
</sect2>
<sect2 id="section.caching">
<title>Caching</title>
<para>
Smarty can cache the output of your generated templates. By default
this is disabled. If you <link linkend="setting.caching">enable
this is disabled. If you <link linkend="variable.caching">enable
caching</link>, Smarty will store a copy of the generated template
output, and use this until the copy <link
linkend="setting.cache.lifetime">expires</link>, regenerating a new
linkend="variable.cache.lifetime">expires</link>, regenerating a new
one. The default cache expire time can be configured from the
class. The exception to the rule is the <link
linkend="builtin.functions.insert">insert</link> tag. Anything
@@ -173,16 +178,19 @@
</sect2>
</sect1>
</chapter>
<chapter>
<chapter id="installation">
<title>Installation</title>
<sect1>
<sect1 id="installation.requirements">
<title>Requirements</title>
<para>
Smarty requires PHP 4.0.4pl1 or later. See the
<link linkend="bugs">BUGS</link> section for caveats.
</para>
</sect1>
<sect1>
<sect1 id="installation.smarty">
<title>Installing Smarty</title>
<para>
Installing Smarty is fairly straightforward, there are a few things to
@@ -232,7 +240,7 @@
</para>
<example>
<title>Example of installing Smarty</title>
<programlisting>
<screen>
# be sure you are in the web server document tree
# this assumes your web server runs as user "nobody"
# and you are in a un*x environment
@@ -243,29 +251,31 @@ chmod 700 templates_c
# if you are using caching, do the following
mkdir cache
chown nobody:nobody cache
chmod 700 cache</programlisting>
chmod 700 cache</screen>
</example>
<para>
Next, try running the index.php script from your web browser.
</para>
</sect1>
</chapter>
<chapter>
<chapter id="variable.up.smarty">
<title>Setting up Smarty</title>
<para>
There are several variables that are at the top of the Smarty.class.php
file. The default settings work for all of the examples and tutorials.
</para>
<sect1>
<sect1 id="smarty.constants">
<title>Constants</title>
<para></para>
<sect2 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 the include_path will be
used to locate the files. If defined, the path must end with a
slash.
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>
@@ -277,10 +287,12 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
</example>
</sect2>
</sect1>
<sect1>
<title>Configuration variables</title>
<sect1 id="smarty.variables">
<title>Variables</title>
<para></para>
<sect2 id="setting.template.dir">
<sect2 id="variable.template.dir">
<title>$template_dir</title>
<para>
This is the name of the default template directory. If you do
@@ -294,7 +306,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
the web server document root.
</para>
</sect2>
<sect2 id="setting.compile.dir">
<sect2 id="variable.compile.dir">
<title>$compile_dir</title>
<para>
This is the name of the directory where compiled templates are
@@ -312,7 +324,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
the web server document root.
</para>
</sect2>
<sect2 id="setting.config.dir">
<sect2 id="variable.config.dir">
<title>$config_dir</title>
<para>
This is the directory used to store config files used in the
@@ -325,7 +337,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
the web server document root.
</para>
</sect2>
<sect2 id="setting.plugins.dir">
<sect2 id="variable.plugins.dir">
<title>$plugins_dir</title>
<para>
This is the directory where Smarty will look for the plugins that
@@ -334,7 +346,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
only one plugins directory.
</para>
</sect2>
<sect2 id="setting.debugging">
<sect2 id="variable.debugging">
<title>$debugging</title>
<para>
This enables the <link
@@ -347,7 +359,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
NOTE: This was added to Smarty 1.4.3.
</para>
</sect2>
<sect2 id="setting.debug.tpl">
<sect2 id="variable.debug.tpl">
<title>$debug_tpl</title>
<para>
This is the name of the template file used for the debugging
@@ -357,7 +369,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
NOTE: This was added to Smarty 1.4.3.
</para>
</sect2>
<sect2 id="setting.debugging.ctrl">
<sect2 id="variable.debugging.ctrl">
<title>$debugging_ctrl</title>
<para>
This allows alternate ways to enable debugging. NONE means no
@@ -370,7 +382,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
NOTE: This was added to Smarty 1.4.4.
</para>
</sect2>
<sect2 id="setting.global.assign">
<sect2 id="variable.global.assign">
<title>$global_assign</title>
<para>
This is a list of variables that are always implicitly assigned
@@ -390,7 +402,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
<link linkend="builtin.variable.smarty">$smarty</link> variable.
</para>
</sect2>
<sect2 id="setting.undefined">
<sect2 id="variable.undefined">
<title>$undefined</title>
<para>
This sets the value of $undefined for Smarty, default is null.
@@ -415,11 +427,11 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
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="setting.force.compile">$force_compile</link> or <link
linkend="variable.force.compile">$force_compile</link> or <link
linkend="api.clear.compiled.tpl">clear_compiled_tpl</link>.
</para>
</sect2>
<sect2 id="setting.force.compile">
<sect2 id="variable.force.compile">
<title>$force_compile</title>
<para>
This forces Smarty to (re)compile templates on every
@@ -429,7 +441,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
is enabled, the cache file(s) will be regenerated every time.
</para>
</sect2>
<sect2 id="setting.caching">
<sect2 id="variable.caching">
<title>$caching</title>
<para>
This tells Smarty whether or not to cache the output of the
@@ -448,7 +460,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
will always be regenerated. (added to Smarty 1.4.7)
</para>
</sect2>
<sect2 id="setting.cache.dir">
<sect2 id="variable.cache.dir">
<title>$cache_dir</title>
<para>
This is the name of the directory where template caches are
@@ -467,7 +479,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
the web server document root.
</para>
</sect2>
<sect2 id="setting.cache.lifetime">
<sect2 id="variable.cache.lifetime">
<title>$cache_lifetime</title>
<para>
This is the length of time in seconds that a template cache is
@@ -478,7 +490,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
Smarty 1.3.0)
</para>
</sect2>
<sect2 id="setting.cache.handler.func">
<sect2 id="variable.cache.handler.func">
<title>$cache_handler_func</title>
<para>
You can supply a custom function to handle cache files instead
@@ -486,36 +498,24 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
custom cache handler function section for details.
</para>
</sect2>
<sect2 id="setting.check.if.modified">
<sect2 id="variable.check.if.modified">
<title>$check_if_modified</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 {insert} tags.
cached content without <command>{insert}</command> tags.
</para>
</sect2>
<sect2 id="setting.default.template.handler.func">
<sect2 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>
</sect2>
<sect2 id="setting.tpl.file.ext">
<title>$tpl_file_ext</title>
<para>
This is the extention used for template files. By default this
is ".tpl". All other files in the template directory are
ignored.
</para>
<para>
NOTE: $tpl_file_ext is no longer needed in 1.4.0. This is kept
for backward compatability.
</para>
</sect2>
<sect2 id="setting.php.handling">
<sect2 id="variable.php.handling">
<title>$php_handling</title>
<para>
This tells Smarty how to handle PHP code embedded in the
@@ -539,7 +539,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
<link linkend="variable.modifiers">modifiers</link> instead.
</para>
</sect2>
<sect2 id="setting.security">
<sect2 id="variable.security">
<title>$security</title>
<para>
$security true/false, default is false. Security is good for
@@ -566,14 +566,14 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
NOTE: Security features were added to Smarty 1.4.3.
</para>
</sect2>
<sect2 id="setting.secure.dir">
<sect2 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>
</sect2>
<sect2 id="setting.security.settings">
<sect2 id="variable.security.settings">
<title>$security_settings</title>
<para>
These are used to override or specify the security settings when
@@ -593,7 +593,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
PHP functions used as variable modifiers.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="setting.trusted.dir">
<sect2 id="variable.trusted.dir">
<title>$trusted_dir</title>
<para>
$trusted_dir is only for use when $security is enabled.
@@ -603,55 +603,35 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
included. New in Smarty 1.5.0.
</para>
</sect2>
<sect2 id="setting.left.delimiter">
<sect2 id="variable.left.delimiter">
<title>$left_delimiter</title>
<para>
This is the left delimiter used by the template language.
Default is "{".
</para>
</sect2>
<sect2 id="setting.right.delimiter">
<sect2 id="variable.right.delimiter">
<title>$right_delimiter</title>
<para>
This is the right delimiter used by the template language.
Default is "}".
</para>
</sect2>
<sect2 id="setting.custom.funcs">
<title>$custom_funcs</title>
<para>
This is a mapping of the names of <link
linkend="custom.functions">custom functions</link> in the
template to the names of functions in PHP. The default custom
functions that come bundled with Smarty are located in
Smarty.addons.php.
</para>
</sect2>
<sect2 id="setting.custom.mods">
<title>$custom_mods</title>
<para>
This is a mapping of the names of variable
<link linkend="variable.modifiers">modifiers</link> in the template to
the names of functions in PHP. The default variable modifiers
that come bundled with Smarty are located in
Smarty.addons.php.
</para>
</sect2>
<sect2 id="setting.show.info.header">
<sect2 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>
</sect2>
<sect2 id="setting.show.info.include">
<sect2 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>
</sect2>
<sect2 id="setting.compiler.class">
<sect2 id="variable.compiler.class">
<title>$compiler_class</title>
<para>
Specifies the name of the compiler class that Smarty will use
@@ -659,34 +639,14 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
advanced users only.
</para>
</sect2>
<sect2 id="setting.resource.funcs">
<title>$resource_funcs</title>
<para>
An array of functions that resource handlers are mapped to.
</para>
</sect2>
<sect2 id="setting.prefilter.funcs">
<title>$prefilter_funcs</title>
<para>
An array of functions that templates are filtered through before
compilation.
</para>
</sect2>
<sect2 id="setting.postfilter.funcs">
<title>$postfilter_funcs</title>
<para>
An array of functions that templates are filtered through after
compilation.
</para>
</sect2>
<sect2 id="setting.request.vars.order">
<sect2 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>
</sect2>
<sect2 id="setting.compile.id">
<sect2 id="variable.compile.id">
<title>$compile_id</title>
<para>
Persistant compile identifier. As an alternative to passing the
@@ -696,6 +656,7 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
</sect2>
</sect1>
</chapter>
<chapter>
<title>Smarty API</title>
<para>
@@ -710,8 +671,6 @@ require_once(SMARTY_DIR."Smarty.class.php");</programlisting>
<funcdef>void <function>assign</function></funcdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>assign</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
@@ -749,8 +708,6 @@ $smarty->assign(array("city" => "Lincoln","state" => "Nebraska"));</programlisti
<funcdef>void <function>append</function></funcdef>
<paramdef>mixed <parameter>var</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>append</function></funcdef>
<paramdef>string <parameter>varname</parameter></paramdef>
@@ -1132,7 +1089,7 @@ $smarty->unregister_resource("db");</programlisting>
<para>
This returns true if there is a valid cache for this template.
This only works if <link
linkend="setting.caching">caching</link> is set to true. This
linkend="variable.caching">caching</link> is set to true. This
was added to Smarty 1.3.0.
</para>
<example>
@@ -2122,11 +2079,15 @@ pass=foobar
variable named $return. As of 1.4.5, this behavior was changed to use
the name attribute, so update your templates accordingly.
</para>
<caution>
<para>
TECHNICAL NOTE: Be careful when capturing {insert} output. If you
have caching turned on and you have {insert} commands that you
expect to run within cached content, do not capture this content.
Be careful when capturing <command>{insert}</command> output. If
you have caching turned on and you have <command>{insert}</command>
commands that you expect to run within cached content, do not
capture this content.
</para>
</caution>
<para>
<example>
<title>capturing template content</title>
<programlisting>
@@ -2142,6 +2103,7 @@ pass=foobar
&lt;/tr&gt;
{/if}</programlisting>
</example>
</para>
</sect2>
<sect2 id="builtin.functions.configload">
<title>config_load</title>
@@ -2513,13 +2475,13 @@ index.tpl
executed on every invocation of the template.
</para>
<para>
Let's say you have a template with a banner slot at the top of the
page. The banner can contain any mixture of HTML, images, flash,
etc. so we can't just use a static link here, and we don't want
this contents cached with the page. In comes the insert tag: the
template knows #banner_location_id# and #site_id# values (gathered
from a config file), and needs to call a function to get the banner
contents.
Let's say you have a template with a banner slot at the top of
the page. The banner can contain any mixture of HTML, images,
flash, etc. so we can't just use a static link here, and we
don't want this contents cached with the page. In comes the
insert tag: the template knows #banner_location_id# and
#site_id# values (gathered from a config file), and needs to
call a function to get the banner contents.
</para>
<example>
<title>function insert</title>
@@ -2707,7 +2669,7 @@ OUTPUT:
<para>
php tags allow php to be embedded directly into the template. They
will not be escaped, regardless of the <link
linkend="setting.php.handling">$php_handling</link> setting. This
linkend="variable.php.handling">$php_handling</link> setting. This
is for advanced users only, not normally needed. This was added to
1.4.0.
</para>
@@ -5768,12 +5730,14 @@ s m o k e r s a r e p. . .</programlisting>
The plugin files must be named as follows:
<blockquote>
<para>
<emphasis>type</emphasis>.<emphasis>name</emphasis>.php
<filename>
<replaceable>type</replaceable>.<replaceable>name</replaceable>.php
</filename>
</para>
</blockquote>
</para>
<para>
<literal>type</literal> is one of these plugin types:
Where <literal>type</literal> is one of these plugin types:
<itemizedlist spacing=compact>
<listitem><simpara>function</simpara></listitem>
<listitem><simpara>modifier</simpara></listitem>
@@ -5785,7 +5749,7 @@ s m o k e r s a r e p. . .</programlisting>
</itemizedlist>
</para>
<para>
<literal>name</literal> should be a valid identifier (letters,
And <literal>name</literal> should be a valid identifier (letters,
numbers, and underscores only).
</para>
<para>
@@ -5797,7 +5761,7 @@ s m o k e r s a r e p. . .</programlisting>
The plugin functions inside the plugin files must be named as follows:
<blockquote>
<para>
smarty_<emphasis>type</emphasis>_<emphasis>name</emphasis>()
<function>smarty_<replaceable>type</replaceable>_<replaceable>name</replaceable></function>
</para>
</blockquote>
</para>
@@ -5812,8 +5776,8 @@ s m o k e r s a r e p. . .</programlisting>
</para>
<note>
<para>
Note that pre/postfilters still have to be correctly
named even though the names are not really used for anything.
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>
@@ -5828,14 +5792,16 @@ s m o k e r s a r e p. . .</programlisting>
</para>
<para>
For the plugins that are registered at runtime, the name of the plugin
function does not have to follow the naming convention.
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>
@@ -5844,7 +5810,7 @@ require_once SMARTY_DIR . 'plugins/function.html_options.php';</programlisting>
<sect1 id="plugins.functions"><title>Template Functions</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>func_name</function></funcdef>
<funcdef>void <function>smarty_function_<replaceable>name</replaceable></function></funcdef>
<paramdef>array <parameter>$params</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
@@ -5852,8 +5818,10 @@ require_once SMARTY_DIR . 'plugins/function.html_options.php';</programlisting>
<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. $params['start'] or
use extract($params) to import them into the symbol table.
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
@@ -5902,13 +5870,10 @@ function smarty_function_eightball($params, &amp;$smarty)
</para>
<para>
which can be used in the template as:
<informalexample>
</para>
<programlisting>
Question: Will we ever have time travel?
Answer: {eightball}.</programlisting>
</informalexample>
</para>
<para>
<example>
<title>function plugin without output</title>
@@ -5945,9 +5910,14 @@ function smarty_function_assign($params, &amp;$smarty)
</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>modifier_name</function></funcdef>
<funcdef>mixed <function>smarty_modifier_<replaceable>name</replaceable></function></funcdef>
<paramdef>mixed <parameter>$value</parameter></paramdef>
<paramdef>[mixed <parameter>$param1</parameter>, ...]</paramdef>
</funcprototype>
@@ -5989,6 +5959,7 @@ function smarty_modifier_capitalize($string)
}
?&gt;</programlisting>
</example>
<para></para>
<example>
<title>more complex modifier plugin</title>
<programlisting>
@@ -6035,7 +6006,7 @@ function smarty_modifier_truncate($string, $length = 80, $etc = '...',
</para>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>compiler_name</function></funcdef>
<funcdef>mixed <function>smarty_compiler_<replaceable>name</replaceable></function></funcdef>
<paramdef>string <parameter>$tag_arg</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
@@ -6072,15 +6043,17 @@ function smarty_compiler_tplheader($tag_arg, &$smarty)
?&gt;</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>
&lt;php
echo 'index.tpl compiled at 2002-02-20 20:02';
?&gt;</programlisting>
</para>
</example>
</sect1>
@@ -6092,7 +6065,7 @@ echo 'index.tpl compiled at 2002-02-20 20:02';
</para>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>prefilter_name</function></funcdef>
<funcdef>string <function>smarty_prefilter_<replaceable>name</replaceable></function></funcdef>
<paramdef>string <parameter>$source</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
@@ -6106,8 +6079,8 @@ echo 'index.tpl compiled at 2002-02-20 20:02';
</para>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>postfilter_name</function></funcdef>
<paramdef>string <parameter>$compiled_source</parameter></paramdef>
<funcdef>string <function>smarty_postfilter_<replaceable>name</replaceable></function></funcdef>
<paramdef>string <parameter>$compiled</parameter></paramdef>
<paramdef>object <parameter>&$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
@@ -6177,75 +6150,178 @@ echo 'index.tpl compiled at 2002-02-20 20:02';
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>rsrc_source</function></funcdef>
<paramdef>string <parameter>$name</parameter></paramdef>
<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>rsrc_timestamp</function></funcdef>
<paramdef>string <parameter>$name</parameter></paramdef>
<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>rsrc_is_secure</function></funcdef>
<paramdef>string <parameter>$name</parameter></paramdef>
<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>rsrc_is_trusted</function></funcdef>
<paramdef>string <parameter>$name</parameter></paramdef>
<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.
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 by reference variable
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.
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 not used for
non-template resources but should still be defined.
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 not used for template resources but should still be
defined.
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></programlisting>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: resource.db.php
* Type: resource
* Name: db
* Purpose: Fetches templates from a database
* -------------------------------------------------------------
*/
function smarty_resource_db_source($tpl_name, &amp;$tpl_source, &amp;$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, &amp;$tpl_timestamp, &amp;$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, &amp;$smarty)
{
// assume all templates are secure
return true;
}
function smarty_resource_db_trusted($tpl_name, &amp;$smarty)
{
// not used for templates
}
?&gt;</programlisting>
</example>
</sect1>
<sect1 id="plugins.inserts"><title>inserts</title>
<sect1 id="plugins.inserts"><title>Inserts</title>
<para>
Insert plugins are used to implement functions that are invoked by
<link linkend="builtin.functions.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></programlisting>
<programlisting>
&lt;?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: insert.time.php
* Type: time
* Name: time
* Purpose: Inserts current date/time according to format
* -------------------------------------------------------------
*/
function smarty_insert_time($params, &amp;$smarty)
{
if (empty($params['format'])) {
$smarty->trigger_error("insert time: missing 'format' parameter");
return;
}
$datetime = strftime($params['format']);
return $datetime;
}
?&gt;</programlisting>
</example>
</sect1>
</chapter>
<chapter id="chapter.debugging.console">
<title>Debugging Console</title>
<para>
@@ -6260,7 +6336,7 @@ echo 'index.tpl compiled at 2002-02-20 20:02';
for the current page. To disable the debugging console, set $debugging to
false. You can also temporarily turn on the debugging console by putting
SMARTY_DEBUG in the URL if you enable this option with <link
linkend="setting.debugging.ctrl">$debugging_ctrl</link>.
linkend="variable.debugging.ctrl">$debugging_ctrl</link>.
</para>
<para>
TECHNICAL NOTE: The debugging console does not work when you use the fetch()