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-28 22:41:41 +00:00
parent 8a24a176d2
commit b32c582f45
4 changed files with 620 additions and 645 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
TESTIMONIALS Normal file
View File

@@ -0,0 +1,9 @@
"I just got my first paying contract for a local small business and in my
program I'm using Smarty. Smarty is an absolute joy to work with -
at first, I didn't like the idea of populating variables/arrays and then
assigning those directly (since I'd been using FastTemplates for so long),
but after using this system for a while, I don't think I can ever go back
(I even switched my Perl template engine to HTML-Template-2.4 which
operates on the same concepts). Anyway, thanks for saving me time and
headache!"
-- Brian E. Lozier

20
docs/appendixes.sgml
View File

@@ -3,7 +3,7 @@
<chapter id="troubleshooting">
<title>Troubleshooting</title>
<para></para>
<sect1>
<sect1 id="smarty.php.errors">
<title>Smarty/PHP errors</title>
<para>
Smarty can catch many errors such as missing tag attributes
@@ -55,7 +55,7 @@ Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75
<title>Tips & Tricks</title>
<para>
</para>
<sect1>
<sect1 id="tips.blank.var.handling">
<title>Blank Variable Handling</title>
<para>
There may be times when you want to print a default value for an empty
@@ -82,7 +82,8 @@ Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75
{$title|default:"&amp;nbsp;"}</programlisting>
</example>
</sect1>
<sect1>
<sect1 id="tips.default.var.handling">
<title>Default Variable Handling</title>
<para>
If a variable is used frequently throughout your templates, applying
@@ -100,7 +101,7 @@ Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75
{$title}</programlisting>
</example>
</sect1>
<sect1>
<sect1 id="tips.passing.vars">
<title>Passing variable title to header template</title>
<para>
When the majority of your templates use the same headers and footers, it
@@ -154,7 +155,7 @@ footer.tpl
<emphasis>default</emphasis> variable modifier.
</para>
</sect1>
<sect1>
<sect1 id="tips.dates">
<title>Dates</title>
<para>
As a rule of thumb, always pass dates to Smarty as timestamps.
@@ -213,7 +214,7 @@ function makeTimeStamp($year="",$month="",$day="")
}</programlisting>
</example>
</sect1>
<sect1>
<sect1 id="tips.wap">
<title>WAP/WML</title>
<para>
WAP/WML templates require a php Content-Type header to be passed along
@@ -353,7 +354,7 @@ index.tpl
Stock Name: {$ticker_name} Stock Price: {$ticker_price}</programlisting>
</example>
</sect1>
<sect1>
<sect1 id="tips.obfuscating.email">
<title>Obfuscating E-mail Addresses</title>
<para>
Do you ever wonder how your E-mail address gets on so many spam mailing
@@ -388,9 +389,8 @@ href="mailto:%62%6f%62%40%6d%65%2e%6e%65%74"&gt;&amp;#x62;&amp;#x6f;&amp;#x62;&a
<note>
<title>Technical Note</title>
<para>
This method isn't 100% foolproof. Although highly unlikely,
a spammer could conceivably write his e-mail collecter to decode these
values.
This method isn't 100% foolproof. Although highly unlikely, a spammer
could conceivably write his e-mail collector to decode these values.
</para>
</note>
</sect1>

349
docs/designers.sgml
View File

@@ -1,4 +1,4 @@
<part>
<part id="smarty.for.designers">
<title>Smarty For Template Designers</title>
<chapter id="language">
<title>Template Language</title>
@@ -141,7 +141,7 @@
&lt;body bgcolr="{#bgcolor#}"&gt;</programlisting>
</para>
<sect2>
<sect2 id="language.assigned.variables">
<title>Variables assigned from PHP</title>
<para>
Variables that are assigned from PHP are referenced by preceding
@@ -162,7 +162,7 @@ Hello Doug, glad to see you could make it.
Your last login was on January 11th, 2001.</programlisting>
</example>
<sect3>
<sect3 id="language.variables.assoc.arrays">
<title>Associative arrays</title>
<para>
You can also reference associative array variables that are
@@ -170,7 +170,7 @@ Your last login was on January 11th, 2001.</programlisting>
symbol.
</para>
<example>
<title>displaying assigned associative array variables</title>
<title>accessing associative array variables</title>
<programlisting>
{$Contacts.fax}&lt;br&gt;
{$Contacts.email}&lt;br&gt;
@@ -187,14 +187,14 @@ zaphod@slartibartfast.com&lt;br&gt;
</programlisting>
</example>
</sect3>
<sect3>
<sect3 id="language.variables.array.indexes">
<title>Array indexes</title>
<para>
You can reference arrays by their index, much like native PHP
syntax.
</para>
<example>
<title>displaying arrays by index</title>
<title>accessing arrays by index</title>
<programlisting>
{$Contacts[0]}&lt;br&gt;
{$Contacts[1]}&lt;br&gt;
@@ -203,14 +203,14 @@ zaphod@slartibartfast.com&lt;br&gt;
{$Contacts[0][1]}&lt;br&gt;</programlisting>
</example>
</sect3>
<sect3>
<sect3 id="language.variables.objects">
<title>Objects</title>
<para>
Properties of objects assigned from PHP can be referenced
by specifying the property name after the '-&gt;' symbol.
</para>
<example>
<title>displaying object properties</title>
<title>accessing object properties</title>
<programlisting>
name: {$person-&gt;name}&lt;br&gt;
email: {$person-&gt;email}&lt;br&gt;
@@ -221,19 +221,17 @@ name: Zaphod Beeblebrox&lt;br&gt;
email: zaphod@slartibartfast.com&lt;br&gt;</programlisting>
</example>
</sect3>
</sect2>
</sect2>
<sect2>
<sect2 id="language.config.variables">
<title>Variables loaded from config files</title>
<para>
Variables that are passed in from config files are displayed by enclosing
them with hash marks (#) and enclosing the variable in delimiters
like so: {#varname#}
Variables that are loaded from the config files are referenced by enclosing
them within hash marks (#).
</para>
<example>
<title>displaying config variables</title>
<title>config variables</title>
<programlisting>
&lt;html&gt;
&lt;title&gt;{#pageTitle#}&lt;/title&gt;
@@ -249,43 +247,31 @@ email: zaphod@slartibartfast.com&lt;br&gt;</programlisting>
&lt;/html&gt;</programlisting>
</example>
<para>
Config file variables cannot be displayed until
Config file variables cannot be used until
after they are loaded in from a config file. This procedure is
explained later in this document under
<link linkend="builtin.functions.configload">config_load</link>.
<command>config_load</command>.
</para>
</sect2>
<sect2>
<title>Variables internal to template</title>
<para>
Variables that are internal to the templates are displayed by using
the special variable {$smarty}. For instance, you can reference the
current date/time with {$smarty.now}, or <link
linkend="builtin.functions.section">section loops</link> have
properties that are internal variables.
</para>
</sect2>
<sect2 id="builtin.variable.smarty">
<title>{$smarty} reserved variable</title>
<para>
The reserved {$smarty} variable can be used to access several
special template variables. The full list of them follows.
</para>
<para>
The special variable {$smarty} was added to Smarty 1.4.4.
</para>
<sect3>
<title>Request variables</title>
<para>
The request variables such as get, post, cookies, server,
environment, and session variables can be accessed as demonstrated
in the examples below:
</para>
<example>
<sect2 id="language.variables.smarty">
<title>{$smarty} reserved variable</title>
<para>
The reserved {$smarty} variable can be used to access several
special template variables. The full list of them follows.
</para>
<title>displaying request variables</title>
<programlisting>
<sect3 id="language.variables.smarty.request">
<title>Request variables</title>
<para>
The request variables such as get, post, cookies, server,
environment, and session variables can be accessed as demonstrated
in the examples below:
</para>
<example>
<title>displaying request variables</title>
<programlisting>
{* display the variable "page" given in the URL, or from a form using the GET method *}
{$smarty.get.page}
@@ -309,7 +295,7 @@ email: zaphod@slartibartfast.com&lt;br&gt;</programlisting>
</example>
</sect3>
<sect3>
<sect3 id="language.variables.smarty.now">
<title>Current timestamp</title>
<para>
The current timestamp can be accessed with {$smarty.now}. The
@@ -326,7 +312,7 @@ email: zaphod@slartibartfast.com&lt;br&gt;</programlisting>
</example>
</sect3>
<sect3>
<sect3 id="language.variables.smarty.capture">
<title>Output capture buffer</title>
<para>
The output captured via {capture}..{/capture} construct can be
@@ -335,7 +321,7 @@ email: zaphod@slartibartfast.com&lt;br&gt;</programlisting>
</para>
</sect3>
<sect3>
<sect3 id="language.variables.smarty.loops">
<title>Loop properties</title>
<para>
{$smarty} variable can be used to refer to 'section' and
@@ -344,43 +330,46 @@ email: zaphod@slartibartfast.com&lt;br&gt;</programlisting>
<link linkend="builtin.functions.foreach">foreach</link>.
</para>
</sect3>
</sect2>
</sect1>
<sect1 id="variable.modifiers">
<title>Variable Modifiers</title>
<para>
Variable modifiers are a bit different than <link
linkend="bundled.plugins.commands">custom functions</link>. Variable modifiers
alter variable contents before they are displayed to the template. All
modifiers will get the value of the variable as the first argument, and
must return a single value. Modifier parameters are separated by
colons. Any additional parameters passed to a modifier are passed as-is
positionally, much like calling a PHP function. You can also use native
PHP functions as modifiers, but only if they expect the correct
arguments. If they do not, you can always write a wrapper function in
Smarty to get what you want. You can chain as many modifiers together
on a variable as you like, separating each with a vertical pipe "|".
</para>
<para>
NOTE: if you apply a modifier to an array instead of a single value
variable, the modifier will be applied to every value in that array. If
you really want the entire array passed to the modifier, you must
prepend it with an "@" sign like so: {$articleTitle|@count} (this will
print out the number of elements in the $articleTitle array.)
</para>
<sect2 id="language.builtin.modifiers">
<title>Built-in Modifiers</title>
<sect3>
<title>capitalize</title>
<para>
This is used to capitalize the first letter of all words in a variable.
</para>
<example>
<title>capitalize</title>
<programlisting>
<sect1 id="language.modifiers">
<title>Variable Modifiers</title>
<para>
Variable modifiers can be applied to any variable to alter its contents. To
apply a modifier, specify the variable followed by the <literal>|</literal>
(pipe) and the modifier name. A modifier may accept additional parameters
that affect its behavior. These parameters follow the modifer name and are
separated by <literal>:</literal> (colon).
</para>
<example>
<title>modifier example</title>
<programlisting>
{* Uppercase the title *}
&lt;h2&gt;{$title|upper}&lt;/h2&gt;
{* Truncate the topic to 40 characters use ... at the end *}
Topic: {$topic|truncate:40:"..."}</programlisting>
</example>
<para>
If you apply a modifier to an array variable instead of a single value variable,
the modifier will be applied to every value in that array. If you really want
the modifier to work on an entire array as a value, you must prepend the
modifier name with an <literal>@</literal> symbol like so:
<literal>{$articleTitle|@count}</literal> (this will print out the number of
elements in the $articleTitle array.)
</para>
<sect2 id="language.builtin.modifiers">
<title>Built-in Modifiers</title>
<sect3>
<title>capitalize</title>
<para>
This is used to capitalize the first letter of all words in a variable.
</para>
<example>
<title>capitalize</title>
<programlisting>
{$articleTitle}
{$articleTitle|capitalize}
@@ -1196,19 +1185,20 @@ from dad she hasn't seen in years.
Blind woman gets new kidney fr
om dad she hasn't seen in years.</programlisting>
</example>
</sect3>
</sect2>
<sect2 id="language.combining.modifiers">
<title>Combining Modifiers</title>
<para>
You can combine as many modifiers as you like on a single variable.
This allows the ability to combine the application of different
modifiers to a single variable. The modifiers will be applied to
the variable in the order they are combined, from left to right.
</para>
<example>
<title>combining modifiers</title>
<programlisting>
</sect3>
</sect2>
<sect2 id="language.combining.modifiers">
<title>Combining Modifiers</title>
<para>
You can apply as many modifiers as you like to a variable. The modifiers
will be applied to the variable in the order they are combined, from left
to right. The modifier have to be separated with a <literal>|</literal>
(pipe) symbol.
</para>
<example>
<title>combining modifiers</title>
<programlisting>
{$articleTitle}
{$articleTitle|upper|spacify}
{$articleTitle|lower|spacify|truncate}
@@ -1223,9 +1213,9 @@ S M O K E R S A R E P R O D U C T I V E , B U T D E A T H C U T S E
s m o k e r s a r e p r o d u c t i v e , b u t d e a t h c u t s...
s m o k e r s a r e p r o d u c t i v e , b u t . . .
s m o k e r s a r e p. . .</programlisting>
</example>
</example>
</sect2>
</sect1>
</sect1>
<sect1 id="language.builtin.functions">
<title>Built-in Functions</title>
@@ -1344,9 +1334,9 @@ s m o k e r s a r e p. . .</programlisting>
</informaltable>
<para>
This function is used for loading in variables from a
configuration file into the template. You must have the Config_file.class.php
file somewhere in your PHP include path for config_load to work properly.
See <link linkend="config.files">Config Files</link> for more info.
configuration file into the template.
See <link linkend="config.files">Config Files</link> for more
info.
</para>
<example>
<title>function config_load</title>
@@ -2570,14 +2560,14 @@ OUTPUT:
</sect2>
</sect1>
<sect1 id="language.more.functions">
<sect1 id="language.custom.functions">
<title>Custom Functions</title>
<para>
Smarty comes with several additional functions that you can
use in the templates.
</para>
<sect2 id="language.custom.functions">
<sect2 id="language.more.functions">
<title>Additional Functions</title>
<sect3 id="language.function.assign">
<title>assign</title>
@@ -4086,24 +4076,21 @@ OUTPUT:
</sect3>
</sect2>
</sect1>
</chapter>
<chapter id="config.files">
<title>Config Files</title>
<para>
Config files are handy for designers to manage global template
variables from one file. One example is template colors. Normally if
you wanted to change the color scheme of an application, you would have
to go through each and every template file and change the colors. With
a config file, the colors can be kept in one place, and only one file
needs to be updated. Note that to use config files, you must place the
Config_File.class.php in your PHP include path. Config_File.class.php
comes bundled with Smarty. Smarty will implicitly include the file if
you don't already include it in your application.
</para>
<example>
<title>Example of config file syntax</title>
<programlisting>
<title>Config Files</title>
<para>
Config files are handy for designers to manage global template
variables from one file. One example is template colors. Normally if
you wanted to change the color scheme of an application, you would have
to go through each and every template file and change the colors. With
a config file, the colors can be kept in one place, and only one file
needs to be updated.
</para>
<example>
<title>Example of config file syntax</title>
<programlisting>
# global variables
pageTitle = "Main Menu"
bodyBgColor = #000000
@@ -4125,75 +4112,73 @@ Intro = """This is a value that spans more
host=my.domain.com
db=ADDRESSBOOK
user=php-user
pass=foobar
</programlisting>
</example>
<para>
Values of config file variables can be in quotes, but not necessary.
You can use either single or double quotes. If you have a value that
spans more than one line, enclose the entire value with triple quotes
("""). You can put comments into config files by any syntax that is
not a valid config file syntax. We recommend using a hashmark (#) at the
beginning of the line.
</para>
<para>
This config file example has two sections. Section names are enclosed
in brackets []. The four variables at the top are global
variables, or variables not within a section. These variables are
always loaded from the config file.
If a particular section is loaded, then the global variables and the
variables from that section are loaded. If a variable exists both as
a global and in a section, the section variable is used. If you name two
variables the same within a section, the last one will be used.
</para>
<para>
Config files are loaded into templates with the built-in function
called <link linkend="builtin.functions.configload">config_load</link>.
</para>
<para>
You can hide variables or entire sections by prepending the variable
name or section name with a period. This is useful if your
application reads the config files and gets sensitive data from them
that the template engine does not need. If you have third parties
doing template editing, you can be certain that they cannot read
sensitive data from the config file by loading it into the template.
This is new in Smarty 1.4.6.
</para>
</chapter>
pass=foobar</programlisting>
</example>
<para>
Values of config file variables can be in quotes, but not necessary.
You can use either single or double quotes. If you have a value that
spans more than one line, enclose the entire value with triple quotes
("""). You can put comments into config files by any syntax that is not
a valid config file syntax. We recommend using a <literal>#</literal>
(hash) at the beginning of the line.
</para>
<para>
This config file example has two sections. Section names are enclosed in
brackets []. Section names can be arbitrary strings not containing
<literal>[</literal> or <literal>]</literal> symbols. The four variables
at the top are global variables, or variables not within a section.
These variables are always loaded from the config file. If a particular
section is loaded, then the global variables and the variables from that
section are also loaded. If a variable exists both as a global and in a
section, the section variable is used. If you name two variables the
same within a section, the last one will be used.
</para>
<para>
Config files are loaded into templates with the built-in function
<command>config_load</command>.
</para>
<para>
You can hide variables or entire sections by prepending the variable
name or section name with a period. This is useful if your application
reads the config files and gets sensitive data from them that the
template engine does not need. If you have third parties doing template
editing, you can be certain that they cannot read sensitive data from
the config file by loading it into the template.
</para>
</chapter>
<chapter id="chapter.debugging.console">
<title>Debugging Console</title>
<para>
There is a dubugging console included with Smarty. The console informs you
of all the included templates, assigned variables and config file variables
for the current invocation of the template. A template named "debug.tpl" is
included with the distribution of Smarty which controls the formatting of
the console. Set $debugging to true in Smarty, and if needed set $debug_tpl
to the template resource path for debug.tpl (this is in $template_dir by
default.) When you load the page, a javascript console window should pop up
and give you the names of all the included templates and assigned variables
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="variable.debugging.ctrl">$debugging_ctrl</link>.
There is a debugging console included with Smarty. The console informs you
of all the included templates, assigned variables and config file variables
for the current invocation of the template. A template named "debug.tpl" is
included with the distribution of Smarty which controls the formatting of
the console. Set $debugging to true in Smarty, and if needed set $debug_tpl
to the template resource path for debug.tpl (this is in $template_dir by
default.) When you load the page, a javascript console window should pop up
and give you the names of all the included templates and assigned variables
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="variable.debugging.ctrl">$debugging_ctrl</link>.
</para>
<note>
<title>Technical Note</title>
<para>
The debugging console does not work when you use the fetch()
API, only when using display(). It is a set of javascript statements added
to the very bottom of the generated template. If you do not like javascript,
you can edit the debug.tpl template to format the output however you like.
Debug data is not cached and debug.tpl info is not included in the output of
the debug console.
</para>
<title>Technical Note</title>
<para>
The debugging console does not work when you use the fetch()
API, only when using display(). It is a set of javascript statements added
to the very bottom of the generated template. If you do not like javascript,
you can edit the debug.tpl template to format the output however you like.
Debug data is not cached and debug.tpl info is not included in the output of
the debug console.
</para>
</note>
<note>
<para>
The load times of each template and config file are in seconds, or
fractions thereof.
</para>
</note>
</chapter>
<para>
The load times of each template and config file are in seconds, or
fractions thereof.
</para>
</note>
</chapter>
</part>

887
docs/programmers.sgml
View File

@@ -1,4 +1,4 @@
<part>
<part id="smarty.for.programmersr">
<title>Smarty For Programmers</title>
<chapter id="api">
<title>Smarty API</title>
@@ -139,7 +139,7 @@
$global_assign to a default value.
</para>
</sect2>
<sect2>
<sect2 id="variable.compile.check">
<title>$compile_check</title>
<para>
Upon each invocation of the PHP application, Smarty tests to
@@ -271,7 +271,7 @@
<para>
NOTE: Embedding PHP code into templates is highly discouraged.
Use <link linkend="bundled.plugins.commands">custom functions</link> or
<link linkend="variable.modifiers">modifiers</link> instead.
<link linkend="language.modifiers">modifiers</link> instead.
</para>
</sect2>
<sect2 id="variable.security">
@@ -994,51 +994,439 @@ echo $output;</programlisting>
</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>
<chapter id="advanced.features">
<title>Advanced Features</title>
<sect1 id="advanced.features.prefilters">
<title>Prefilters</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.
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>
&lt;?php
// put this in your application
function remove_dw_comments($tpl_source)
{
return preg_replace("/&lt;!--#.*--&gt;/U","",$tpl_source);
}
// register the prefilter
$smarty->register_prefilter("remove_dw_comments");
$smarty->display("index.tpl");
?&gt;
{* Smarty template index.tpl *}
&lt;!--# this line will get removed by the prefilter --&gt;</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>
&lt;?php
// put this in your application
function add_header_comment($tpl_source)
{
return "&lt;?php echo \"&lt;!-- Created by Smarty! --&gt;\n\" ?&gt;\n".$tpl_source;
}
// register the postfilter
$smarty->register_postfilter("add_header_comment");
$smarty->display("index.tpl");
?&gt;
{* compiled Smarty template index.tpl *}
&lt;!-- Created by Smarty! --&gt;
{* rest of template content... *}</programlisting>
</example>
</sect2>
</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>
&lt;?php
/*
example usage:
include('Smarty.class.php');
include('mysql_cache_handler.php');
$smarty = new Smarty;
$smarty-&gt;cache_handler_func = 'mysql_cache_handler';
$smarty-&gt;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-&gt;_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-&gt;_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-&gt;_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-&gt;_trigger_error_msg("cache_handler: query failed.");
}
$return = $results;
break;
default:
// error, unknown action
$smarty_obj-&gt;_trigger_error_msg("cache_handler: unknown action \"$action\"");
$return = false;
break;
}
mysql_close($link);
return $return;
}
?&gt;</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, &amp;tpl_source, &amp;$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>
&lt;?php
// put this function somewhere in your application
function make_template ($resource_type, $resource_name, &amp;$template_source, &amp;$template_timestamp, &amp;$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';
?&gt;</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>
@@ -1376,7 +1764,8 @@ echo 'index.tpl compiled at 2002-02-20 20:02';
</example>
</sect1>
<sect1 id="plugins.prefilters.postfilters"><title>Prefilters/Postfilters</title>
<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
@@ -1640,412 +2029,4 @@ function smarty_insert_time($params, &amp;$smarty)
</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>.
</para>
<sect2>
<title>Example of a Template Prefilter</title>
<para>
Create a function in your application that Smarty will use as a
template prefilter. Smarty will pass the template source code as the
first argument, an expect the function to return the resulting
template source code.
</para>
<para>
NOTE: As of Smarty 1.4.5, the Smarty object is passed as the second
argument. This way you can reference and modify information in the
Smarty object from within the prefilter function.
</para>
<example>
<title>using a template prefilter</title>
<programlisting>
// put this in your application, or in Smarty.addons.php
function remove_dw_comments($tpl_source) {
return preg_replace("/&lt;!--#.*--&gt;/U","",$tpl_source);
}
// register the prefilter
$smarty->register_prefilter("remove_dw_comments");
$smarty->display("index.tpl");
{* from within Smarty template *}
&lt;!--# this line will get removed by the prefilter --&gt;</programlisting>
</example>
</sect2>
</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>.
</para>
<sect2>
<title>Example of a Template Postfilter</title>
<para>
Create a function in your application that Smarty will use as a
template postfilter. Smarty will pass the template source code as the
first argument, an expect the function to return the resulting
template source code.
</para>
<para>
The Smarty object is passed as the second argument. This way you
can reference and modify information in the Smarty object from
within the prefilter function.
</para>
<example>
<title>using a template postfilter</title>
<programlisting>
// this program puts a
// put this in your application, or in Smarty.addons.php
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");
{* from within Smarty template *}
<!-- Created by Smarty! -->
{* rest of template content... *}</programlisting>
</example>
</sect2>
</sect1>
<sect1 id="section.template.cache.handler.func">
<title>Cache Handling 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>
<sect2>
<title>Example of a Template Cache Handling Function</title>
<para>
Create a function in your application that Smarty will use as a
cache handler. Set the name of it in the $cache_handler_func 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 pass this 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>
&lt;?php
/*
example usage:
include('Smarty.class.php');
include('mysql_cache_handler.php');
$smarty = new Smarty;
$smarty-&gt;cache_handler_func='mysql_cache_handler';
$smarty-&gt;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-&gt;_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-&gt;_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-&gt;_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-&gt;_trigger_error_msg("cache_handler: query failed.");
}
$return = $results;
break;
default:
// error, unknown action
$smarty_obj-&gt;_trigger_error_msg("cache_handler: unknown action \"$action\"");
$return = false;
break;
}
mysql_close($link);
return $return;
}
?&gt;
</programlisting>
</example>
</sect2>
</sect1>
<sect1 id="template.resources">
<title>Resources</title>
<para>
Your 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>
<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>
<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>
<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, &amp;tpl_source, &amp;$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>
<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>
// from PHP script
// put this function somewhere in your application
function make_template ($resource_type, $resource_name, &amp;$template_source,
&amp;$template_timestamp, &amp;$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>
</part>