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

English dir split

Browse Source
This commit is contained in:
didou
2004-03-28 15:15:38 +00:00
parent 710d11f55d
commit 518b5047c6
21 changed files with 10057 additions and 9748 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
docs/en/appendixes/bugs.xml Normal file
View File

@@ -0,0 +1,29 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="bugs">
<title>BUGS</title>
<para>
Check the BUGS file that comes with the latest distribution of Smarty, or
check the website.
</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

31
docs/en/appendixes/resources.xml Normal file
View File

@@ -0,0 +1,31 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="resources">
<title>Resources</title>
<para>
Smarty's homepage is located at http://smarty.php.net/.
You can join the mailing list by sending an e-mail to
smarty-general-subscribe@lists.php.net. An archive of the mailing list can be
viewed at http://marc.theaimsgroup.com/?l=smarty&amp;r=1&amp;w=2
</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

77
docs/en/appendixes.xml → docs/en/appendixes/tips.xml
View File

@@ -1,62 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?> <?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ --> <!-- $Revision$ -->
<part id="appendixes">
<title>Appendixes</title>
<chapter id="troubleshooting">
<title>Troubleshooting</title>
<para></para>
<sect1 id="smarty.php.errors">
<title>Smarty/PHP errors</title>
<para>
Smarty can catch many errors such as missing tag attributes
or malformed variable names. If this happens, you will see an error
similar to the following:
</para>
<example>
<title>Smarty errors</title>
<screen>
<![CDATA[
Warning: Smarty: [in index.tpl line 4]: syntax error: unknown tag - '%blah'
in /path/to/smarty/Smarty.class.php on line 1041
Fatal error: Smarty: [in index.tpl line 28]: syntax error: missing section name
in /path/to/smarty/Smarty.class.php on line 1041
]]>
</screen>
</example>
<para>
Smarty shows you the template name, the line number and the error.
After that, the error consists of the actual line number in the Smarty
class that the error occured.
</para>
<para>
There are certain errors that Smarty cannot catch, such as missing
close tags. These types of errors usually end up in PHP compile-time
parsing errors.
</para>
<example>
<title>PHP parsing errors</title>
<screen>
<![CDATA[
Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75
]]>
</screen>
</example>
<para>
When you encounter a PHP parsing error, the error line number will
correspond to the compiled PHP script, not the template itself. Usually
you can look at the template and spot the syntax error. Here are some
common things to look for: missing close tags for {if}{/if} or
{section}{/section}, or syntax of logic within an {if} tag. If you
can't find the error, you might have to open the compiled PHP file and
go to the line number to figure out where the corresponding error is in
the template.
</para>
</sect1>
</chapter>
<chapter id="tips"> <chapter id="tips">
<title>Tips &amp; Tricks</title> <title>Tips &amp; Tricks</title>
<para> <para>
@@ -381,25 +324,7 @@ Send inquiries to
</para> </para>
</note> </note>
</sect1> </sect1>
</chapter> </chapter>
<chapter id="resources">
<title>Resources</title>
<para>
Smarty's homepage is located at http://smarty.php.net/.
You can join the mailing list by sending an e-mail to
smarty-general-subscribe@lists.php.net. An archive of the mailing list can be
viewed at http://marc.theaimsgroup.com/?l=smarty&amp;r=1&amp;w=2
</para>
</chapter>
<chapter id="bugs">
<title>BUGS</title>
<para>
Check the BUGS file that comes with the latest distribution of Smarty, or
check the website.
</para>
</chapter>
</part>
<!-- Keep this comment at the end of the file <!-- Keep this comment at the end of the file
Local variables: Local variables:
mode: sgml mode: sgml

77
docs/en/appendixes/troubleshooting.xml Normal file
View File

@@ -0,0 +1,77 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="troubleshooting">
<title>Troubleshooting</title>
<para></para>
<sect1 id="smarty.php.errors">
<title>Smarty/PHP errors</title>
<para>
Smarty can catch many errors such as missing tag attributes
or malformed variable names. If this happens, you will see an error
similar to the following:
</para>
<example>
<title>Smarty errors</title>
<screen>
<![CDATA[
Warning: Smarty: [in index.tpl line 4]: syntax error: unknown tag - '%blah'
in /path/to/smarty/Smarty.class.php on line 1041
Fatal error: Smarty: [in index.tpl line 28]: syntax error: missing section name
in /path/to/smarty/Smarty.class.php on line 1041
]]>
</screen>
</example>
<para>
Smarty shows you the template name, the line number and the error.
After that, the error consists of the actual line number in the Smarty
class that the error occured.
</para>
<para>
There are certain errors that Smarty cannot catch, such as missing
close tags. These types of errors usually end up in PHP compile-time
parsing errors.
</para>
<example>
<title>PHP parsing errors</title>
<screen>
<![CDATA[
Parse error: parse error in /path/to/smarty/templates_c/index.tpl.php on line 75
]]>
</screen>
</example>
<para>
When you encounter a PHP parsing error, the error line number will
correspond to the compiled PHP script, not the template itself. Usually
you can look at the template and spot the syntax error. Here are some
common things to look for: missing close tags for {if}{/if} or
{section}{/section}, or syntax of logic within an {if} tag. If you
can't find the error, you might have to open the compiled PHP file and
go to the line number to figure out where the corresponding error is in
the template.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

6132
docs/en/designers.xml
View File

File diff suppressed because it is too large Load Diff

58
docs/en/designers/chapter-debugging-console.xml Normal file
View File

@@ -0,0 +1,58 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="chapter.debugging.console">
<title>Debugging Console</title>
<para>
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 SMARTY_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 see the available variables for a particular
templates, see the <link linkend="language.function.debug">{debug}</link>
template function. 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>
</note>
<note>
<para>
The load times of each template and config file are in seconds, or
fractions thereof.
</para>
</note>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

90
docs/en/designers/config-files.xml Normal file
View File

@@ -0,0 +1,90 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<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.
</para>
<example>
<title>Example of config file syntax</title>
<programlisting>
# global variables
pageTitle = "Main Menu"
bodyBgColor = #000000
tableBgColor = #000000
rowBgColor = #00ff00
[Customer]
pageTitle = "Customer Info"
[Login]
pageTitle = "Login"
focus = "username"
Intro = """This is a value that spans more
than one line. you must enclose
it in triple quotes."""
# hidden section
[.Database]
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 <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>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

229
docs/en/designers/language-basic-syntax.xml Normal file
View File

@@ -0,0 +1,229 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="language.basic.syntax">
<title>Basic Syntax</title>
<para>
All Smarty template tags are enclosed within delimiters. By
default, these delimiters are <literal>{</literal> and
<literal>}</literal>, but they can be changed.
</para>
<para>
For these examples, we will assume that you are using the default
delimiters. In Smarty, all content outside of delimiters is displayed as
static content, or unchanged. When Smarty encounters template tags, it
attempts to interpret them, and displays the appropriate output in their
place.
</para>
<sect1 id="language.syntax.comments">
<title>Comments</title>
<para>
Template comments are surrounded by asterisks, and that is surrounded
by the delimiter tags like so: {* this is a comment *}
Smarty comments are not displayed in the final output of the template.
They are used for making internal notes in the templates.
</para>
<example>
<title>Comments</title>
<programlisting>
{* Smarty *}
{* include the header file here *}
{include file="header.tpl"}
{include file=$includeFile}
{include file=#includeFile#}
{* display dropdown lists *}
&lt;SELECT name=company&gt;
{html_options values=$vals selected=$selected output=$output}
&lt;/SELECT&gt;</programlisting>
</example>
</sect1>
<sect1 id="language.syntax.functions">
<title>Functions</title>
<para>
Each Smarty tag either prints a
<link linkend="language.variables">variable</link> or invokes some sort
of function. Functions are processed and displayed by enclosing the
function and its attributes into delimiters like so: {funcname
attr1="val" attr2="val"}.
</para>
<example>
<title>function syntax</title>
<programlisting>
<![CDATA[
{config_load file="colors.conf"}
{include file="header.tpl"}
{if $highlight_name}
Welcome, <font color="{#fontColor#}">{$name}!</font>
{else}
Welcome, {$name}!
{/if}
{include file="footer.tpl"}
]]>
</programlisting>
</example>
<para>
Both built-in functions and custom functions have the same syntax in
the templates. Built-in functions are the inner workings of Smarty,
such as <command>if</command>, <command>section</command> and
<command>strip</command>. They cannot be modified. Custom functions are
additional functions implemented via plugins. They can be modified to
your liking, or you can add new ones. <command>html_options</command> and
<command>html_select_date</command> are examples of custom functions.
</para>
</sect1>
<sect1 id="language.syntax.attributes">
<title>Attributes</title>
<para>
Most of the functions take attributes that specify or modify
their behavior. Attributes to Smarty functions are much like HTML
attributes. Static values don't have to be enclosed in quotes, but it
is recommended for literal strings. Variables may also be used, and
should not be in quotes.
</para>
<para>
Some attributes require boolean values (true or false). These can be
specified as either unquoted <literal>true</literal>,
<literal>on</literal>, and <literal>yes</literal>, or
<literal>false</literal>, <literal>off</literal>, and
<literal>no</literal>.
</para>
<example>
<title>function attribute syntax</title>
<programlisting>
{include file="header.tpl"}
{include file=$includeFile}
{include file=#includeFile#}
{html_select_date display_days=yes}
&lt;SELECT name=company&gt;
{html_options values=$vals selected=$selected output=$output}
&lt;/SELECT&gt;</programlisting>
</example>
</sect1>
<sect1 id="language.syntax.quotes">
<title>Embedding Vars in Double Quotes</title>
<para>
Smarty will recognize assigned variables embedded in double quotes so long
as the variables contain only numbers, letters, underscores and brackets
[]. With any other characters (period, object reference, etc.) the variable
must be surrounded by backticks.
</para>
<example>
<title>embedded quotes syntax</title>
<programlisting>
SYNTAX EXAMPLES:
{func var="test $foo test"} &lt;-- sees $foo
{func var="test $foo_bar test"} &lt;-- sees $foo_bar
{func var="test $foo[0] test"} &lt;-- sees $foo[0]
{func var="test $foo[bar] test"} &lt;-- sees $foo[bar]
{func var="test $foo.bar test"} &lt;-- sees $foo (not $foo.bar)
{func var="test `$foo.bar` test"} &lt;-- sees $foo.bar
PRACTICAL EXAMPLES:
{include file="subdir/$tpl_name.tpl"} &lt;-- will replace $tpl_name with value
{cycle values="one,two,`$smarty.config.myval`"} &lt;-- must have backticks</programlisting>
</example>
</sect1>
<sect1 id="language.math">
<title>Math</title>
<para>
Math can be applied directly to variable values.
</para>
<example>
<title>math examples</title>
<programlisting>
{$foo+1}
{$foo*$bar}
{* some more complicated examples *}
{$foo-&gt;bar-$bar[1]*$baz-&gt;foo-&gt;bar()-3*7}
{if ($foo+$bar.test%$baz*134232+10+$b+10)}
{$foo|truncate:"`$fooTruncCount/$barTruncFactor-1`"}
{assign var="foo" value="`$foo+$bar`"}</programlisting>
</example>
</sect1>
<sect1 id="language.escaping">
<title>Escaping Smarty Parsing</title>
<para>
It is sometimes desirable or even necessary to have Smarty ignore sections it
would otherwise parse. A classic example is embedding Javascript or CSS code in
a template. The problem arises as those languages use the { and } characters
which are also the default delimiters for Smarty.
</para>
<para>
The simplest thing is to avoid the situation altogether by separating your Javascript
and CSS code into their own files and then using standard HTML methods to access them.
</para>
<para>Including literal content is possible using <link linkend="language.function.literal">{literal} .. {/literal}</link> blocks.
Similar to HTML entity usage, you can use <link linkend="language.function.ldelim">{ldelim}</link> and <link linkend="language.function.ldelim">{rdelim}</link>
to display the current delimiters.
</para>
<para>
It is often convenient to simply change Smarty's <link linkend="variable.left.delimiter">$left_delimiter</link> and
<link linkend="variable.right.delimiter">$right_delimiter</link>.
</para>
<example>
<title>changing delimiters example</title>
<programlisting>
$smarty = new Smarty;
$smarty->left_delimiter = '&lt;!--{';
$smarty->right_delimiter = '}--&gt;';
$smarty->assign('foo', 'bar');
$smarty->display('example.tpl');
--- example.tpl
&lt;script language="javascript"&gt;
var foo = &lt;!--{$foo}--&gt;;
function dosomething() {
alert("foo is " + foo);
}
dosomething();
&lt;/script&gt;
</programlisting>
</example>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

1602
docs/en/designers/language-builtin-functions.xml Normal file
View File

File diff suppressed because it is too large Load Diff

56
docs/en/designers/language-combining-modifiers.xml Normal file
View File

@@ -0,0 +1,56 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="language.combining.modifiers">
<title>Combining Modifiers</title>
<para>
You can apply any number of modifiers to a variable. They will be
applied in the order they are combined, from left to right. They must
be separated with a <literal>|</literal> (pipe) character.
</para>
<example>
<title>combining modifiers</title>
<programlisting>
index.php:
$smarty = new Smarty;
$smarty-&gt;assign('articleTitle', 'Smokers are Productive, but Death Cuts Efficiency.');
$smarty-&gt;display('index.tpl');
index.tpl:
{$articleTitle}
{$articleTitle|upper|spacify}
{$articleTitle|lower|spacify|truncate}
{$articleTitle|lower|truncate:30|spacify}
{$articleTitle|lower|spacify|truncate:30:". . ."}
OUTPUT:
Smokers are Productive, but Death Cuts Efficiency.
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 F F I C I E N C Y .
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>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

2683
docs/en/designers/language-custom-functions.xml Normal file
View File

File diff suppressed because it is too large Load Diff

1201
docs/en/designers/language-modifiers.xml Normal file
View File

File diff suppressed because it is too large Load Diff

354
docs/en/designers/language-variables.xml Normal file
View File

@@ -0,0 +1,354 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="language.variables">
<title>Variables</title>
<para>
Smarty has several different types of variables. The type of the variable
depends on what symbol it is prefixed with (or enclosed within).
</para>
<para>
Variables in Smarty can be either displayed directly or used as arguments
for function attributes and modifiers, inside conditional expressions,
etc. To print a variable, simply enclose it in the delimiters so that it
is the only thing contained between them. Examples:
<programlisting>
{$Name}
{$Contacts[row].Phone}
&lt;body bgcolor="{#bgcolor#}"&gt;</programlisting>
</para>
<sect1 id="language.assigned.variables">
<title>Variables assigned from PHP</title>
<para>
Variables that are assigned from PHP are referenced by preceding them with
a dollar sign <literal>$</literal>. Variables assigned from within the
template with the <link linkend="language.function.assign">assign</link>
function are also displayed this way.
</para>
<example>
<title>assigned variables</title>
<programlisting>
Hello {$firstname}, glad to see you could make it.
&lt;p&gt;
Your last login was on {$lastLoginDate}.
OUTPUT:
Hello Doug, glad to see you could make it.
&lt;p&gt;
Your last login was on January 11th, 2001.</programlisting>
</example>
<sect2 id="language.variables.assoc.arrays">
<title>Associative arrays</title>
<para>
You can also reference associative array variables that are
assigned from PHP by specifying the key after the '.' (period)
symbol.
</para>
<example>
<title>accessing associative array variables</title>
<programlisting>
index.php:
$smarty = new Smarty;
$smarty-&gt;assign('Contacts',
array('fax' => '555-222-9876',
'email' => 'zaphod@slartibartfast.com',
'phone' => array('home' => '555-444-3333',
'cell' => '555-111-1234')));
$smarty-&gt;display('index.tpl');
index.tpl:
{$Contacts.fax}&lt;br&gt;
{$Contacts.email}&lt;br&gt;
{* you can print arrays of arrays as well *}
{$Contacts.phone.home}&lt;br&gt;
{$Contacts.phone.cell}&lt;br&gt;
OUTPUT:
555-222-9876&lt;br&gt;
zaphod@slartibartfast.com&lt;br&gt;
555-444-3333&lt;br&gt;
555-111-1234&lt;br&gt;</programlisting>
</example>
</sect2>
<sect2 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>accessing arrays by index</title>
<programlisting>
index.php:
$smarty = new Smarty;
$smarty-&gt;assign('Contacts',
array('555-222-9876',
'zaphod@slartibartfast.com',
array('555-444-3333',
'555-111-1234')));
$smarty-&gt;display('index.tpl');
index.tpl:
{$Contacts[0]}&lt;br&gt;
{$Contacts[1]}&lt;br&gt;
{* you can print arrays of arrays as well *}
{$Contacts[2][0]}&lt;br&gt;
{$Contacts[2][1]}&lt;br&gt;
OUTPUT:
555-222-9876&lt;br&gt;
zaphod@slartibartfast.com&lt;br&gt;
555-444-3333&lt;br&gt;
555-111-1234&lt;br&gt;</programlisting>
</example>
</sect2>
<sect2 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>accessing object properties</title>
<programlisting>
name: {$person-&gt;name}&lt;br&gt;
email: {$person-&gt;email}&lt;br&gt;
OUTPUT:
name: Zaphod Beeblebrox&lt;br&gt;
email: zaphod@slartibartfast.com&lt;br&gt;</programlisting>
</example>
</sect2>
</sect1>
<sect1 id="language.config.variables">
<title>Variables loaded from config files</title>
<para>
Variables that are loaded from the config files are referenced by
enclosing them within hash marks (#), or with the smarty variable
<link
linkend="language.variables.smarty.config">$smarty.config</link>.
The second syntax is useful for embedding into quoted attribute
values.
</para>
<example>
<title>config variables</title>
<programlisting>
foo.conf:
pageTitle = "This is mine"
bodyBgColor = "#eeeeee"
tableBorderSize = "3"
tableBgColor = "#bbbbbb"
rowBgColor = "#cccccc"
index.tpl:
{config_load file="foo.conf"}
&lt;html&gt;
&lt;title&gt;{#pageTitle#}&lt;/title&gt;
&lt;body bgcolor="{#bodyBgColor#}"&gt;
&lt;table border="{#tableBorderSize#}" bgcolor="{#tableBgColor#}"&gt;
&lt;tr bgcolor="{#rowBgColor#}"&gt;
&lt;td&gt;First&lt;/td&gt;
&lt;td&gt;Last&lt;/td&gt;
&lt;td&gt;Address&lt;/td&gt;
&lt;/tr&gt;
&lt;/table&gt;
&lt;/body&gt;
&lt;/html&gt;
index.tpl: (alternate syntax)
{config_load file="foo.conf"}
&lt;html&gt;
&lt;title&gt;{$smarty.config.pageTitle}&lt;/title&gt;
&lt;body bgcolor="{$smarty.config.bodyBgColor}"&gt;
&lt;table border="{$smarty.config.tableBorderSize}" bgcolor="{$smarty.config.tableBgColor}"&gt;
&lt;tr bgcolor="{$smarty.config.rowBgColor}"&gt;
&lt;td&gt;First&lt;/td&gt;
&lt;td&gt;Last&lt;/td&gt;
&lt;td&gt;Address&lt;/td&gt;
&lt;/tr&gt;
&lt;/table&gt;
&lt;/body&gt;
&lt;/html&gt;
OUTPUT: (same for both examples)
&lt;html&gt;
&lt;title&gt;This is mine&lt;/title&gt;
&lt;body bgcolor="#eeeeee"&gt;
&lt;table border="3" bgcolor="#bbbbbb"&gt;
&lt;tr bgcolor="#cccccc"&gt;
&lt;td&gt;First&lt;/td&gt;
&lt;td&gt;Last&lt;/td&gt;
&lt;td&gt;Address&lt;/td&gt;
&lt;/tr&gt;
&lt;/table&gt;
&lt;/body&gt;
&lt;/html&gt;</programlisting>
</example>
<para>
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
<command>config_load</command>.
</para>
</sect1>
<sect1 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>
<sect2 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 value of page from URL (GET) http://www.domain.com/index.php?page=foo *}
{$smarty.get.page}
{* display the variable "page" from a form (POST) *}
{$smarty.post.page}
{* display the value of the cookie "username" *}
{$smarty.cookies.username}
{* display the server variable "SERVER_NAME" *}
{$smarty.server.SERVER_NAME}
{* display the system environment variable "PATH" *}
{$smarty.env.PATH}
{* display the php session variable "id" *}
{$smarty.session.id}
{* display the variable "username" from merged get/post/cookies/server/env *}
{$smarty.request.username}</programlisting>
</example>
<para>
Note: For historical reasons {$SCRIPT_NAME} can be accessed
directly though {$smarty.server.SCRIPT_NAME} is the
proposed way to access this value.
</para>
</sect2>
<sect2 id="language.variables.smarty.now">
<title>{$smarty.now}</title>
<para>
The current timestamp can be accessed with {$smarty.now}. The
number reflects the number of seconds passed since the so-called
Epoch (January 1, 1970) and can be passed directly to
date_format modifier for display purposes.
</para>
<example>
<title>using {$smarty.now}</title>
<programlisting>
{* use the date_format modifier to show current date and time *}
{$smarty.now|date_format:"%Y-%m-%d %H:%M:%S"}</programlisting>
</example>
</sect2>
<sect2 id="language.variables.smarty.const">
<title>{$smarty.const}</title>
<para>
You can access PHP constant values directly.
</para>
<example>
<title>using {$smarty.const}</title>
<programlisting>
{$smarty.const._MY_CONST_VAL}</programlisting>
</example>
</sect2>
<sect2 id="language.variables.smarty.capture">
<title>{$smarty.capture}</title>
<para>
The output captured via {capture}..{/capture} construct can be
accessed using {$smarty} variable. See section on
<link linkend="language.function.capture">capture</link> for an example.
</para>
</sect2>
<sect2 id="language.variables.smarty.config">
<title>{$smarty.config}</title>
<para>
{$smarty} variable can be used to refer to loaded config variables.
{$smarty.config.foo} is a synonym for {#foo#}. See the section on
<link linkend="language.function.config.load">config_load</link> for an example.
</para>
</sect2>
<sect2 id="language.variables.smarty.loops">
<title>{$smarty.section}, {$smarty.foreach}</title>
<para>
{$smarty} variable can be used to refer to 'section' and
'foreach' loop properties. See docs for
<link linkend="language.function.section">section</link> and
<link linkend="language.function.foreach">foreach</link>.
</para>
</sect2>
<sect2 id="language.variables.smarty.template">
<title>{$smarty.template}</title>
<para>
This variable contains the name of the current template being
processed.
</para>
</sect2>
<sect2 id="language.variables.smarty.version">
<title>{$smarty.version}</title>
<para>
This variable contains the version of Smarty the template was compiled with.
</para>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

6
docs/en/language-defs.ent Normal file
View File

@@ -0,0 +1,6 @@
<!-- $Revision$ -->
<!ENTITY SMARTYManual "Smarty Manual">
<!ENTITY SMARTYDesigners "Smarty For Template Designers">
<!ENTITY SMARTYProgrammers "Smarty For Programmers">
<!ENTITY Appendixes "Appendixes">

3540
docs/en/programmers.xml
View File

File diff suppressed because it is too large Load Diff

579
docs/en/programmers/advanced-features.xml Normal file
View File

@@ -0,0 +1,579 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="advanced.features">
<title>Advanced Features</title>
<sect1 id="advanced.features.objects">
<title>Objects</title>
<para>
Smarty allows access to PHP objects through the templates. There are
two ways to access them. One way is to register objects to the template,
then use access them via syntax similar to custom functions. The other way
is to assign objects to the templates and access them much like any other
assigned variable. The first method has a much nicer template syntax. It
is also more secure, as a registered object can be restricted to certain
methods or properties. However, a registered object cannot be looped over
or assigned in arrays of objects, etc. The method you choose will be
determined by your needs, but use the first method whenever possible to
keep template syntax to a minimum.
</para>
<para>
If security is enabled, no private methods or functions can be accessed
(begininning with "_"). If a method and property of the same name exist,
the method will be used.
</para>
<para>
You can restrict the methods and properties that can be accessed by
listing them in an array as the third registration parameter.
</para>
<para>
By default, parameters passed to objects through the templates are passed
the same way custom functions get them. An associative array is passed
as the first parameter, and the smarty object as the second. If you want
the parameters passed one at a time for each argument like traditional
object parameter passing, set the fourth registration parameter to false.
</para>
<para>
The optional fifth parameter has only effect with
<parameter>format</parameter> being <literal>true</literal>
and contains a list ob methods that should be treated as
blocks. That means these methods have a closing tag in the
template
(<literal>{foobar->meth2}...{/foobar->meth2}</literal>) and
the parameters to the methods have the same synopsis as the
parameters for block-function-plugins: They get 4 parameters
<parameter>$params</parameter>,
<parameter>$content</parameter>,
<parameter>&amp;$smarty</parameter> and
<parameter>&amp;$repeat</parameter> and they also behave like
block-function-plugins.
</para>
<example>
<title>using a registered or assigned object</title>
<programlisting role="php">
<![CDATA[
<?php
// the object
class My_Object {
function meth1($params, &amp;$smarty_obj) {
return "this is my meth1";
}
}
$myobj = new My_Object;
// registering the object (will be by reference)
$smarty->register_object("foobar",$myobj);
// if we want to restrict access to certain methods or properties, list them
$smarty->register_object("foobar",$myobj,array('meth1','meth2','prop1'));
// if you want to use the traditional object parameter format, pass a boolean of false
$smarty->register_object("foobar",$myobj,null,false);
// We can also assign objects. Assign by ref when possible.
$smarty->assign_by_ref("myobj", $myobj);
$smarty->display("index.tpl");
?>
TEMPLATE:
{* access our registered object *}
{foobar->meth1 p1="foo" p2=$bar}
{* you can also assign the output *}
{foobar->meth1 p1="foo" p2=$bar assign="output"}
the output was {$output}
{* access our assigned object *}
{$myobj->meth1("foo",$bar)}
]]>
</programlisting>
</example>
</sect1>
<sect1 id="advanced.features.prefilters">
<title>Prefilters</title>
<para>
Template prefilters are PHP functions that your templates are ran through
before they are compiled. This is good for preprocessing your templates
to remove unwanted comments, keeping an eye on what people are putting
in their templates, etc. Prefilters can be either
<link linkend="api.register.prefilter">registered</link> or loaded from
the plugins directory by using
<link linkend="api.load.filter">load_filter()</link> function or by
setting
<link linkend="variable.autoload.filters">$autoload_filters</link> variable.
Smarty will pass the template source code as the first argument, and
expect the function to return the resulting template source code.
</para>
<example>
<title>using a template prefilter</title>
<programlisting role="php">
<![CDATA[
<?php
// put this in your application
function remove_dw_comments($tpl_source, &amp;$smarty)
{
return preg_replace("/<!--#.*-->/U","",$tpl_source);
}
// register the prefilter
$smarty->register_prefilter("remove_dw_comments");
$smarty->display("index.tpl");
?>
{* Smarty template index.tpl *}
<!--# this line will get removed by the prefilter -->
]]>
</programlisting>
</example>
</sect1>
<sect1 id="advanced.features.postfilters">
<title>Postfilters</title>
<para>
Template postfilters are PHP functions that your templates are ran through
after they are compiled. Postfilters can be either
<link linkend="api.register.postfilter">registered</link> or loaded
from the plugins directory by using
<link linkend="api.load.filter">load_filter()</link> function or by
setting
<link linkend="variable.autoload.filters">$autoload_filters</link>
variable. Smarty will pass the compiled template code as the first
argument, and expect the function to return the result of the
processing.
</para>
<example>
<title>using a template postfilter</title>
<programlisting role="php">
<![CDATA[
<?php
// put this in your application
function add_header_comment($tpl_source, &amp;$smarty)
{
return "<?php echo \"<!-- Created by Smarty! -->;\n\" ?>;\n".$tpl_source;
}
// register the postfilter
$smarty->register_postfilter("add_header_comment");
$smarty->display("index.tpl");
?>
{* compiled Smarty template index.tpl *}
<!-- Created by Smarty! -->
{* rest of template content... *}
]]>
</programlisting>
</example>
</sect1>
<sect1 id="advanced.features.outputfilters">
<title>Output Filters</title>
<para>
When the template is invoked via display() or fetch(), its output can be
sent through one or more output filters. This differs from postfilters
because postfilters operate on compiled templates before they are saved to
the disk, and output filters operate on the template output when it is
executed.
</para>
<para>
Output filters can be either
<link linkend="api.register.outputfilter">registered</link> or loaded
from the plugins directory by using
<link linkend="api.load.filter">load_filter()</link> function or by
setting
<link linkend="variable.autoload.filters">$autoload_filters</link>
variable. Smarty will pass the template output as the first argument,
and expect the function to return the result of the processing.
</para>
<example>
<title>using a template outputfilter</title>
<programlisting role="php">
<![CDATA[
<?php
// put this in your application
function protect_email($tpl_output, &amp;$smarty)
{
$tpl_output =
preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
'$1%40$2', $tpl_output);
return $tpl_output;
}
// register the outputfilter
$smarty->register_outputfilter("protect_email");
$smarty->display("index.tpl");
// now any occurrence of an email address in the template output will have
// a simple protection against spambots
?>
]]>
</programlisting>
</example>
</sect1>
<sect1 id="section.template.cache.handler.func">
<title>Cache Handler Function</title>
<para>
As an alternative to using the default file-based caching mechanism, you
can specify a custom cache handling function that will be used to read,
write and clear cached files.
</para>
<para>
Create a function in your application that Smarty will use as a
cache handler. Set the name of it in the
<link linkend="variable.cache.handler.func">$cache_handler_func</link>
class variable. Smarty will now use this to handle cached data. The
first argument is the action, which will be one of 'read', 'write' and
'clear'. The second parameter is the Smarty object. The third parameter
is the cached content. Upon a write, Smarty passes the cached content
in these parameters. Upon a 'read', Smarty expects your function to
accept this parameter by reference and populate it with the cached
data. Upon a 'clear', pass a dummy variable here since it is not used.
The fourth parameter is the name of the template file (needed for
read/write), the fifth parameter is the cache_id (optional), and the
sixth is the compile_id (optional).
</para>
<para>
Note: The last parameter ($exp_time) was added in Smarty-2.6.0.
</para>
<example>
<title>example using MySQL as a cache source</title>
<programlisting role="php">
<![CDATA[
<?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, &amp;$smarty_obj, &amp;$cache_content, $tpl_file=null, $cache_id=null, $compile_id=null, $exp_time=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. If a resource is not explicitly given the value of <link
linkend="variable.default.resource.type">$default_resource_type</link> is
assumed.
</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 role="php">
<![CDATA[
<?php
$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 role="php">
<![CDATA[
<?php
$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 role="php">
<![CDATA[
<?php
$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 role="php">
<![CDATA[
<?php
// 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, &amp;$tpl_timestamp, &amp;$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, &amp;$smarty_obj)
{
// assume all templates are secure
return true;
}
function db_get_trusted($tpl_name, &amp;$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 role="php">
<![CDATA[
<?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';
?>
]]>
</programlisting>
</example>
</sect2>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

1231
docs/en/programmers/api-functions.xml Normal file
View File

File diff suppressed because it is too large Load Diff

499
docs/en/programmers/api-variables.xml Normal file
View File

@@ -0,0 +1,499 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="api.variables">
<title>Variables</title>
<sect1 id="variable.template.dir">
<title>$template_dir</title>
<para>
This is the name of the default template directory. If you do
not supply a resource type when including files, they will be
found here. By default this is "./templates", meaning that it
will look for the templates directory in the same directory as
the executing php script.
</para>
<note>
<title>Technical Note</title>
<para>
It is not recommended to put this directory under
the web server document root.
</para>
</note>
</sect1>
<sect1 id="variable.compile.dir">
<title>$compile_dir</title>
<para>
This is the name of the directory where compiled templates are
located. By default this is "./templates_c", meaning that it
will look for the compile directory in the same directory as
the executing php script.
</para>
<note>
<title>Technical Note</title>
<para>
This setting must be either a relative or
absolute path. include_path is not used for writing files.
</para>
</note>
<note>
<title>Technical Note</title>
<para>
It is not recommended to put this directory under
the web server document root.
</para>
</note>
</sect1>
<sect1 id="variable.config.dir">
<title>$config_dir</title>
<para>
This is the directory used to store config files used in the
templates. Default is "./configs", meaning that it will look
for the configs directory in the same directory as the
executing php script.
</para>
<note>
<title>Technical Note</title>
<para>
It is not recommended to put this directory under
the web server document root.
</para>
</note>
</sect1>
<sect1 id="variable.plugins.dir">
<title>$plugins_dir</title>
<para>
This is the directories where Smarty will look for the plugins that it
needs. Default is "plugins" under the SMARTY_DIR. If you supply a
relative path, Smarty will first look under the SMARTY_DIR, then
relative to the cwd (current working directory), then relative to each
entry in your PHP include path.
</para>
<note>
<title>Technical Note</title>
<para>
For best performance, do not setup your plugins_dir to have to use the
PHP include path. Use an absolute pathname, or a path relative to
SMARTY_DIR or the cwd.
</para>
</note>
</sect1>
<sect1 id="variable.debugging">
<title>$debugging</title>
<para>
This enables the <link
linkend="chapter.debugging.console">debugging console</link>.
The console is a javascript window that informs you of the
included templates and assigned variables for the current
template page.
</para>
</sect1>
<sect1 id="variable.debug.tpl">
<title>$debug_tpl</title>
<para>
This is the name of the template file used for the debugging console. By
default, it is named debug.tpl and is located in the <link
linkend="constant.smarty.dir">SMARTY_DIR</link>.
</para>
</sect1>
<sect1 id="variable.debugging.ctrl">
<title>$debugging_ctrl</title>
<para>
This allows alternate ways to enable debugging. NONE means no
alternate methods are allowed. URL means when the keyword
SMARTY_DEBUG is found in the QUERY_STRING, debugging is enabled
for that invocation of the script. If $debugging is true, this
value is ignored.
</para>
</sect1>
<sect1 id="variable.undefined">
<title>$undefined</title>
<para>
This sets the value of $undefined for Smarty, default is null.
Currently this is only used to set undefined variables in
$global_assign to a default value.
</para>
</sect1>
<sect1 id="variable.autoload.filters">
<title>$autoload_filters</title>
<para>
If there are some filters that you wish to load on every template
invocation, you can specify them using this variable and Smarty will
automatically load them for you. The variable is an associative array
where keys are filter types and values are arrays of the filter
names. For example:
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$smarty->autoload_filters = array('pre' => array('trim', 'stamp'),
'output' => array('convert'));
?>
]]>
</programlisting>
</informalexample>
</para>
</sect1>
<sect1 id="variable.compile.check">
<title>$compile_check</title>
<para>
Upon each invocation of the PHP application, Smarty tests to see if the
current template has changed (different time stamp) since the last time
it was compiled. If it has changed, it recompiles that template. 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" for
maximal 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 or config file was updated. See <link
linkend="variable.force.compile">$force_compile</link> or <link
linkend="api.clear.compiled.tpl">clear_compiled_tpl</link>.
</para>
</sect1>
<sect1 id="variable.force.compile">
<title>$force_compile</title>
<para>
This forces Smarty to (re)compile templates on every
invocation. This setting overrides $compile_check. By default
this is disabled. This is handy for development and debugging.
It should never be used in a production environment. If caching
is enabled, the cache file(s) will be regenerated every time.
</para>
</sect1>
<sect1 id="variable.caching">
<title>$caching</title>
<para>
This tells Smarty whether or not to cache the output of the templates.
By default this is set to 0, or disabled. If your templates generate
redundant redundant content, it is advisable to turn on caching. This
will result in significant performance gains. You can also have multiple
caches for the same template. A value of 1 or 2 enables caching. 1 tells
Smarty to use the current $cache_lifetime variable to determine if the
cache has expired. A value of 2 tells Smarty to use the cache_lifetime
value at the time the cache was generated. This way you can set the
cache_lifetime just before fetching the template to have granular
control over when that particular cache expires. See also <link
linkend="api.is.cached">is_cached</link>.
</para>
<para>
If $compile_check is enabled, the cached content will be regenerated if
any of the templates or config files that are part of this cache are
changed. If $force_compile is enabled, the cached content will always be
regenerated.
</para>
</sect1>
<sect1 id="variable.cache.dir">
<title>$cache_dir</title>
<para>
This is the name of the directory where template caches are
stored. By default this is "./cache", meaning that it will look
for the cache directory in the same directory as the executing
php script. You can also use your own custom cache handler
function to control cache files, which will ignore this
setting.
</para>
<note>
<title>Technical Note</title>
<para>
This setting must be either a relative or
absolute path. include_path is not used for writing files.
</para>
</note>
<note>
<title>Technical Note</title>
<para>
It is not recommended to put this directory under
the web server document root.
</para>
</note>
</sect1>
<sect1 id="variable.cache.lifetime">
<title>$cache_lifetime</title>
<para>
This is the length of time in seconds that a template cache is valid.
Once this time has expired, the cache will be regenerated. $caching must
be set to "true" for $cache_lifetime to have any purpose. A value of -1
will force the cache to never expire. A value of 0 will cause the cache
to always regenerate (good for testing only, to disable caching a more
efficient method is to set <link
linkend="variable.caching">$caching</link> = false.)
</para>
<para>
If <link linkend="variable.force.compile">$force_compile</link> is
enabled, the cache files will be regenerated every time, effectively
disabling caching. You can clear all the cache files with the <link
linkend="api.clear.all.cache">clear_all_cache()</link> function, or
individual cache files (or groups) with the <link
linkend="api.clear.cache">clear_cache()</link> function.
</para>
<note>
<title>Technical Note</title>
<para>
If you want to give certain templates their own cache lifetime, you could
do this by setting <link linkend="variable.caching">$caching</link> = 2,
then set $cache_lifetime to a unique value just before calling display()
or fetch().
</para>
</note>
</sect1>
<sect1 id="variable.cache.handler.func">
<title>$cache_handler_func</title>
<para>
You can supply a custom function to handle cache files instead
of using the built-in method using the $cache_dir. See the
custom <link linkend="section.template.cache.handler.func">cache
handler function section</link> 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.config.overwrite">
<title>$config_overwrite</title>
<para>
If set to true, variables read in from config files will overwrite each
other. Otherwise, the variables will be pushed onto an array. This is
helpful if you want to store arrays of data in config files, just list
each element multiple times. true by default.
</para>
</sect1>
<sect1 id="variable.config.booleanize">
<title>$config_booleanize</title>
<para>
If set to true, config file values of on/true/yes and off/false/no get
converted to boolean values automatically. This way you can use the
values in the template like so: {if #foobar#} ... {/if}. If foobar was
on, true or yes, the {if} statement will execute. true by default.
</para>
</sect1>
<sect1 id="variable.config.read.hidden">
<title>$config_read_hidden</title>
<para>
If set to true, hidden sections (section names beginning with a period)
in config files can be read from templates. Typically you would leave
this false, that way you can store sensitive data in the config files
such as database parameters and not worry about the template loading
them. false by default.
</para>
</sect1>
<sect1 id="variable.config.fix.newlines">
<title>$config_fix_newlines</title>
<para>
If set to true, mac and dos newlines (\r and \r\n) in config files are
converted to \n when they are parsed. true by default.
</para>
</sect1>
<sect1 id="variable.default.template.handler.func">
<title>$default_template_handler_func</title>
<para>
This function is called when a template cannot be obtained from
its resource.
</para>
</sect1>
<sect1 id="variable.php.handling">
<title>$php_handling</title>
<para>
This tells Smarty how to handle PHP code embedded in the
templates. There are four possible settings, default being
SMARTY_PHP_PASSTHRU. Note that this does NOT affect php code
within <link linkend="language.function.php">{php}{/php}</link>
tags in the template.
</para>
<itemizedlist>
<listitem><para>SMARTY_PHP_PASSTHRU - Smarty echos tags as-is.</para></listitem>
<listitem><para>SMARTY_PHP_QUOTE - Smarty quotes the tags as
html entities.</para></listitem>
<listitem><para>SMARTY_PHP_REMOVE - Smarty removes the tags from
the templates.</para></listitem>
<listitem><para>SMARTY_PHP_ALLOW - Smarty will execute the tags
as PHP code.</para></listitem>
</itemizedlist>
<para>
NOTE: Embedding PHP code into templates is highly discouraged.
Use <link linkend="language.custom.functions">custom functions</link> or
<link linkend="language.modifiers">modifiers</link> instead.
</para>
</sect1>
<sect1 id="variable.security">
<title>$security</title>
<para>
$security true/false, default is false. Security is good for
situations when you have untrusted parties editing the templates
(via ftp for example) and you want to reduce the risk of system
security compromises through the template language. Turning on
security enforces the following rules to the template language,
unless specifially overridden with $security_settings:
</para>
<itemizedlist>
<listitem><para>If $php_handling is set to SMARTY_PHP_ALLOW, this is
implicitly changed to SMARTY_PHP_PASSTHRU</para></listitem>
<listitem><para>PHP functions are not allowed in IF statements,
except those specified in the $security_settings</para></listitem>
<listitem><para>templates can only be included from directories
listed in the $secure_dir array</para></listitem>
<listitem><para>local files can only be fetched from directories
listed in the $secure_dir array using {fetch}</para></listitem>
<listitem><para>{php}{/php} tags are not allowed</para></listitem>
<listitem><para>PHP functions are not allowed as modifiers, except
those specified in the $security_settings</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="variable.secure.dir">
<title>$secure_dir</title>
<para>
This is an array of all local directories that are considered
secure. {include} and {fetch} use this when security is enabled.
</para>
</sect1>
<sect1 id="variable.security.settings">
<title>$security_settings</title>
<para>
These are used to override or specify the security settings when
security is enabled. These are the possible settings:
</para>
<itemizedlist>
<listitem><para>PHP_HANDLING - true/false. If set to true, the
$php_handling setting is not checked for security.</para></listitem>
<listitem><para>IF_FUNCS - This is an array of the names of permitted
PHP functions in IF statements.</para></listitem>
<listitem><para>INCLUDE_ANY - true/false. If set to true, any
template can be included from the file system, regardless of the
$secure_dir list.</para></listitem>
<listitem><para>PHP_TAGS - true/false. If set to true, {php}{/php}
tags are permitted in the templates.</para></listitem>
<listitem><para>MODIFIER_FUNCS - This is an array of the names of permitted
PHP functions used as variable modifiers.</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="variable.trusted.dir">
<title>$trusted_dir</title>
<para>
$trusted_dir is only for use when $security is enabled. This is an array
of all directories that are considered trusted. Trusted directories are
where you keep php scripts that are executed directly from the templates
with <link linkend="language.function.include.php">{include_php}</link>.
</para>
</sect1>
<sect1 id="variable.left.delimiter">
<title>$left_delimiter</title>
<para>
This is the left delimiter used by the template language.
Default is "{".
</para>
</sect1>
<sect1 id="variable.right.delimiter">
<title>$right_delimiter</title>
<para>
This is the right delimiter used by the template language.
Default is "}".
</para>
</sect1>
<sect1 id="variable.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.request.use.auto.globals">
<title>$request_use_auto_globals</title>
<para>
Specifies if Smarty should use php's $HTTP_*_VARS[]
($request_use_auto_globals=false which is the default value) or
$_*[] ($request_use_auto_globals=true). This affects templates
that make use of {$smarty.request.*}, {$smarty.get.*} etc. .
Caution: If you set $request_use_auto_globals to true, <link
linkend="variable.request.vars.order">variable.request.vars.order
</link> has no effect but php's configuration value
<literal>gpc_order</literal> is used.
</para>
</sect1>
<sect1 id="variable.error.reporting">
<title>$error_reporting</title>
<para>
When this value is set to a non-null-value it's value is
used as php's error_reporting-level inside of display() and
fetch(). When debugging is enabled this value is ignored
and the error-level is left untouched.
</para>
</sect1>
<sect1 id="variable.compile.id">
<title>$compile_id</title>
<para>
Persistant compile identifier. As an alternative to passing the same
compile_id to each and every function call, you can set this compile_id
and it will be used implicitly thereafter.
</para>
</sect1>
<sect1 id="variable.use.sub.dirs">
<title>$use_sub_dirs</title>
<para>
Set this to false if your PHP environment does not allow the creation of
sub directories by Smarty. Sub directories are more efficient, so use them
if you can.
</para>
<note>
<title>Technical Note</title>
<para>
Since Smarty-2.6.2 <varname>use_sub_dirs</varname> defaults to false.
</para>
</note>
</sect1>
<sect1 id="variable.default.modifiers">
<title>$default_modifiers</title>
<para>
This is an array of modifiers to implicitly apply to every variable in a
template. For example, to HTML-escape every variable by default, use
array('escape:"htmlall"'); To make a variable exempt from default
modifiers, pass the special "smarty" modifier with a parameter value of
"nodefaults" modifier to it, such as
{$var|smarty:nodefaults}.
</para>
</sect1>
<sect1 id="variable.default.resource.type">
<title>$default_resource_type</title>
<para>
This tells smarty what resource type to use implicitly. The default value
is 'file', meaning that $smarty->display('index.tpl'); and
$smarty->display('file:index.tpl'); are identical in meaning. See the
<link linkend="template.resources">resource</link> chapter for details.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

451
docs/en/programmers/caching.xml Normal file
View File

@@ -0,0 +1,451 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="caching">
<title>Caching</title>
<para>
Caching is used to speed up a call to <link
linkend="api.display">display()</link> or <link
linkend="api.fetch">fetch()</link> by saving its output to a file. If a
cached version of the call is available, that is displayed instead of
regenerating the output. Caching can speed things up tremendously,
especially templates with longer computation times. Since the output of
display() or fetch() is cached, one cache file could conceivably be made up
of several template files, config files, etc.
</para>
<para>
Since templates are dynamic, it is important to be careful what you are
caching and for how long. For instance, if you are displaying the front page
of your website that does not change its content very often, it might work
well to cache this page for an hour or more. On the other hand, if you are
displaying a page with a weather map containing new information by the
minute, it would not make sense to cache this page.
</para>
<sect1 id="caching.setting.up">
<title>Setting Up Caching</title>
<para>
The first thing to do is enable caching. This is done by setting <link
linkend="variable.caching">$caching</link> = true (or 1.)
</para>
<example>
<title>enabling caching</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->display('index.tpl');
?>
]]>
</programlisting>
</example>
<para>
With caching enabled, the function call to display('index.tpl') will render
the template as usual, but also saves a copy of its output to a file (a
cached copy) in the <link linkend="variable.cache.dir">$cache_dir</link>.
Upon the next call to display('index.tpl'), the cached copy will be used
instead of rendering the template again.
</para>
<note>
<title>Technical Note</title>
<para>
The files in the $cache_dir are named similar to the template name.
Although they end in the ".php" extention, they are not really executable
php scripts. Do not edit these files!
</para>
</note>
<para>
Each cached page has a limited lifetime determined by <link
linkend="variable.cache.lifetime">$cache_lifetime</link>. The default value
is 3600 seconds, or 1 hour. After that time expires, the cache is
regenerated. It is possible to give individual caches their own expiration
time by setting $caching = 2. See the documentation on <link
linkend="variable.cache.lifetime">$cache_lifetime</link> for details.
</para>
<example>
<title>setting cache_lifetime per cache</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = 2; // lifetime is per cache
// set the cache_lifetime for index.tpl to 5 minutes
$smarty->cache_lifetime = 300;
$smarty->display('index.tpl');
// set the cache_lifetime for home.tpl to 1 hour
$smarty->cache_lifetime = 3600;
$smarty->display('home.tpl');
// NOTE: the following $cache_lifetime setting will not work when $caching = 2.
// The cache lifetime for home.tpl has already been set
// to 1 hour, and will no longer respect the value of $cache_lifetime.
// The home.tpl cache will still expire after 1 hour.
$smarty->cache_lifetime = 30; // 30 seconds
$smarty->display('home.tpl');
?>
]]>
</programlisting>
</example>
<para>
If <link linkend="variable.compile.check">$compile_check</link> is enabled,
every template file and config file that is involved with the cache file is
checked for modification. If any of the files have been modified since the
cache was generated, the cache is immediately regenerated. This is a slight
overhead so for optimum performance, leave $compile_check set to false.
</para>
<example>
<title>enabling $compile_check</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->compile_check = true;
$smarty->display('index.tpl');
?>
]]>
</programlisting>
</example>
<para>
If <link linkend="variable.force.compile">$force_compile</link> is enabled,
the cache files will always be regenerated. This effectively turns off
caching. $force_compile is usually for debugging purposes only, a more
efficient way of disabling caching is to set <link
linkend="variable.caching">$caching</link> = false (or 0.)
</para>
<para>
The <link linkend="api.is.cached">is_cached()</link> function
can be used to test if a template has a valid cache or not. If you have a
cached template that requires something like a database fetch, you can use
this to skip that process.
</para>
<example>
<title>using is_cached()</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
if(!$smarty->is_cached('index.tpl')) {
// No cache available, do variable assignments here.
$contents = get_database_contents();
$smarty->assign($contents);
}
$smarty->display('index.tpl');
?>
]]>
</programlisting>
</example>
<para>
You can keep parts of a page dynamic with the <link
linkend="language.function.insert">insert</link> template function. Let's
say the whole page can be cached except for a banner that is displayed down
the right side of the page. By using an insert function for the banner, you
can keep this element dynamic within the cached content. See the
documentation on <link linkend="language.function.insert">insert</link> for
details and examples.
</para>
<para>
You can clear all the cache files with the <link
linkend="api.clear.all.cache">clear_all_cache()</link> function, or
individual cache files (or groups) with the <link
linkend="api.clear.cache">clear_cache()</link> function.
</para>
<example>
<title>clearing the cache</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// clear out all cache files
$smarty->clear_all_cache();
// clear only cache for index.tpl
$smarty->clear_cache('index.tpl');
$smarty->display('index.tpl');
?>
]]>
</programlisting>
</example>
</sect1>
<sect1 id="caching.multiple.caches">
<title>Multiple Caches Per Page</title>
<para>
You can have multiple cache files for a single call to display() or
fetch(). Let's say that a call to display('index.tpl') may have several
different output contents depending on some condition, and you want
separate caches for each one. You can do this by passing a cache_id as the
second parameter to the function call.
</para>
<example>
<title>passing a cache_id to display()</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$my_cache_id = $_GET['article_id'];
$smarty->display('index.tpl',$my_cache_id);
?>
]]>
</programlisting>
</example>
<para>
Above, we are passing the variable $my_cache_id to display() as the
cache_id. For each unique value of $my_cache_id, a separate cache will be
generated for index.tpl. In this example, "article_id" was passed in the
URL and is used as the cache_id.
</para>
<note>
<title>Technical Note</title>
<para>
Be very cautious when passing values from a client (web browser) into
Smarty (or any PHP application.) Although the above example of using the
article_id from the URL looks handy, it could have bad consequences. The
cache_id is used to create a directory on the file system, so if the user
decided to pass an extremely large value for article_id, or write a script
that sends random article_ids at a rapid pace, this could possibly cause
problems at the server level. Be sure to sanitize any data passed in before
using it. In this instance, maybe you know the article_id has a length of
10 characters and is made up of alpha-numerics only, and must be a valid
article_id in the database. Check for this!
</para>
</note>
<para>
Be sure to pass the same cache_id as the
second parameter to <link linkend="api.is.cached">is_cached()</link> and
<link linkend="api.clear.cache">clear_cache()</link>.
</para>
<example>
<title>passing a cache_id to is_cached()</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$my_cache_id = $_GET['article_id'];
if(!$smarty->is_cached('index.tpl',$my_cache_id)) {
// No cache available, do variable assignments here.
$contents = get_database_contents();
$smarty->assign($contents);
}
$smarty->display('index.tpl',$my_cache_id);
?>
]]>
</programlisting>
</example>
<para>
You can clear all caches for a particular cache_id by passing null as the
first parameter to clear_cache().
</para>
<example>
<title>clearing all caches for a particular cache_id</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// clear all caches with "sports" as the cache_id
$smarty->clear_cache(null,"sports");
$smarty->display('index.tpl',"sports");
?>
]]>
</programlisting>
</example>
<para>
In this manner, you can "group" your caches together by giving them the
same cache_id.
</para>
</sect1>
<sect1 id="caching.groups">
<title>Cache Groups</title>
<para>
You can do more elaborate grouping by setting up cache_id groups. This is
accomplished by separating each sub-group with a vertical bar "|" in the
cache_id value. You can have as many sub-groups as you like.
</para>
<example>
<title>cache_id groups</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
// clear all caches with "sports|basketball" as the first two cache_id groups
$smarty->clear_cache(null,"sports|basketball");
// clear all caches with "sports" as the first cache_id group. This would
// include "sports|basketball", or "sports|(anything)|(anything)|(anything)|..."
$smarty->clear_cache(null,"sports");
$smarty->display('index.tpl',"sports|basketball");
?>
]]>
</programlisting>
</example>
<note>
<title>Technical Note</title>
<para>
The cache grouping does NOT use the path to the template as any part of the
cache_id. For example, if you have display('themes/blue/index.tpl'), you
cannot clear the cache for everything under the "themes/blue" directory. If
you want to do that, you must group them in the cache_id, such as
display('themes/blue/index.tpl','themes|blue'); Then you can clear the
caches for the blue theme with clear_cache(null,'themes|blue');
</para>
</note>
</sect1>
<sect1 id="caching.cacheable">
<title>Controlling Cacheability of Plugins' Output</title>
<para>
Since Smarty-2.6.0 plugins the cacheability of plugins can be declared
when registering them. The third parameter to register_block,
register_compiler_function and register_function is called
<parameter>$cacheable</parameter> and defaults to true which is also
the behaviour of plugins in Smarty versions before 2.6.0
</para>
<para>
When registering a plugin with $cacheable=false the plugin is called everytime the page is displayed, even if the page comes from the cache. The plugin function behaves a little like an <link linkend="plugins.inserts">insert</link> function.
</para>
<para>
In contrast to <link linkend="language.function.insert">{insert}</link> the attributes to the plugins are not cached by default. They can be declared to be cached with the fourth parameter <parameter>$cache_attrs</parameter>. <parameter>$cache_attrs</parameter> is an array of attribute-names that should be cached, so the plugin-function get value as it was the time the page was written to cache everytime it is fetched from the cache.
</para>
<example>
<title>Preventing a plugin's output from being cached</title>
<programlisting role="php">
<![CDATA[
index.php:
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
function remaining_seconds($params, &amp;$smarty) {
$remain = $params['endtime'] - time();
if ($remain >=0)
return $remain . " second(s)";
else
return "done";
}
$smarty->register_function('remaining', 'remaining_seconds', false, array('endtime'));
if (!$smarty->is_cached('index.tpl')) {
// fetch $obj from db and assign...
$smarty->assign_by_ref('obj', $obj);
}
$smarty->display('index.tpl');
?>
index.tpl:
Time Remaining: {remain endtime=$obj->endtime}
]]>
</programlisting>
<para>
The number of seconds till the endtime of $obj is reached changes on each display of the page, even if the page is cached. Since the endtime attribute is cached the object only has to be pulled from the database when page is written to the cache but not on subsequent requests of the page.
</para>
</example>
<example>
<title>Preventing a whole passage of a template from being cached</title>
<programlisting role="php">
<![CDATA[
index.php:
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
function smarty_block_dynamic($param, $content, &amp;$smarty) {
return $content;
}
$smarty->register_block('dynamic', 'smarty_block_dynamic', false);
$smarty->display('index.tpl');
?>
index.tpl:
Page created: {"0"|date_format:"%D %H:%M:%S"}
{dynamic}
Now is: {"0"|date_format:"%D %H:%M:%S"}
... do other stuff ...
{/dynamic}
]]>
</programlisting>
</example>
<para>
When reloading the page you will notice that both dates differ. One is "dynamic" one is "static". You can do everything between {dynamic}...{/dynamic} and be sure it will not be cached like the rest of the page.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

832
docs/en/programmers/plugins.xml Normal file
View File

@@ -0,0 +1,832 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="plugins">
<title>Extending Smarty With Plugins</title>
<para>
Version 2.0 introduced the plugin architecture that is used
for almost all the customizable functionality of Smarty. This includes:
<itemizedlist spacing="compact">
<listitem><simpara>functions</simpara></listitem>
<listitem><simpara>modifiers</simpara></listitem>
<listitem><simpara>block functions</simpara></listitem>
<listitem><simpara>compiler functions</simpara></listitem>
<listitem><simpara>prefilters</simpara></listitem>
<listitem><simpara>postfilters</simpara></listitem>
<listitem><simpara>outputfilters</simpara></listitem>
<listitem><simpara>resources</simpara></listitem>
<listitem><simpara>inserts</simpara></listitem>
</itemizedlist>
With the exception of resources, backwards compatibility with the old
way of registering handler functions via register_* API is preserved. If
you did not use the API but instead modified the class variables
<literal>$custom_funcs</literal>, <literal>$custom_mods</literal>, and
other ones directly, then you will need to adjust your scripts to either
use the API or convert your custom functionality into plugins.
</para>
<sect1>
<title>How Plugins Work</title>
<para>
Plugins are always loaded on demand. Only the specific modifiers,
functions, resources, etc invoked in the templates scripts will be
loaded. Moreover, each plugin is loaded only once, even if you have
several different instances of Smarty running within the same request.
</para>
<para>
Pre/postfilters and output filters are a bit of a special case. Since
they are not mentioned in the templates, they must be registered or
loaded explicitly via API functions before the template is processed.
The order in which multiple filters of the same type are executed
depends on the order in which they are registered or loaded.
</para>
<para>
The <link linkend="variable.plugins.dir">plugins directory</link>
can be a string containing a path or an array containing multiple
paths. To install a plugin, simply place it in one of the
directories and Smarty will use it automatically.
</para>
</sect1>
<sect1 id="plugins.naming.conventions">
<title>Naming Conventions</title>
<para>
Plugin files and functions must follow a very specific naming
convention in order to be located by Smarty.
</para>
<para>
The plugin files must be named as follows:
<blockquote>
<para>
<filename>
<replaceable>type</replaceable>.<replaceable>name</replaceable>.php
</filename>
</para>
</blockquote>
</para>
<para>
Where <literal>type</literal> is one of these plugin types:
<itemizedlist spacing="compact">
<listitem><simpara>function</simpara></listitem>
<listitem><simpara>modifier</simpara></listitem>
<listitem><simpara>block</simpara></listitem>
<listitem><simpara>compiler</simpara></listitem>
<listitem><simpara>prefilter</simpara></listitem>
<listitem><simpara>postfilter</simpara></listitem>
<listitem><simpara>outputfilter</simpara></listitem>
<listitem><simpara>resource</simpara></listitem>
<listitem><simpara>insert</simpara></listitem>
</itemizedlist>
</para>
<para>
And <literal>name</literal> should be a valid identifier (letters,
numbers, and underscores only).
</para>
<para>
Some examples: <literal>function.html_select_date.php</literal>,
<literal>resource.db.php</literal>,
<literal>modifier.spacify.php</literal>.
</para>
<para>
The plugin functions inside the plugin files must be named as follows:
<blockquote>
<para>
<function>smarty_<replaceable>type</replaceable>_<replaceable>name</replaceable></function>
</para>
</blockquote>
</para>
<para>
The meanings of <literal>type</literal> and <literal>name</literal> are
the same as before.
</para>
<para>
Smarty will output appropriate error messages if the plugin file it
needs is not found, or if the file or the plugin function are named
improperly.
</para>
</sect1>
<sect1 id="plugins.writing">
<title>Writing Plugins</title>
<para>
Plugins can be either loaded by Smarty automatically from the
filesystem or they can be registered at runtime via one of the
register_* API functions. They can also be unregistered by using
unregister_* API functions.
</para>
<para>
For the plugins that are registered at runtime, the name of the plugin
function(s) does not have to follow the naming convention.
</para>
<para>
If a plugin depends on some functionality provided by another plugin
(as is the case with some plugins bundled with Smarty), then the proper
way to load the needed plugin is this:
</para>
<programlisting>
require_once $smarty->_get_plugin_filepath('function', 'html_options');</programlisting>
<para>
As a general rule, Smarty object is always passed to the plugins
as the last parameter (with two exceptions: modifiers do not get
passed the Smarty object at all and blocks get passed
<parameter>&amp;$repeat</parameter> after the Smarty object to keep
backwards compatibility to older versions of Smarty).
</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>&amp;$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.
</para>
<para>
The output (return value) 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 role="php">
<![CDATA[
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: function.eightball.php
* Type: function
* Name: eightball
* Purpose: outputs a random magic answer
* -------------------------------------------------------------
*/
function smarty_function_eightball($params, &amp;$smarty)
{
$answers = array('Yes',
'No',
'No way',
'Outlook not so good',
'Ask again soon',
'Maybe in your reality');
$result = array_rand($answers);
return $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 role="php">
<![CDATA[
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: function.assign.php
* Type: function
* Name: assign
* Purpose: assign a value to a template variable
* -------------------------------------------------------------
*/
function smarty_function_assign($params, &amp;$smarty)
{
if (empty($params['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($params['var'], $params['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 role="php">
<![CDATA[
<?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 role="php">
<![CDATA[
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: modifier.truncate.php
* Type: modifier
* Name: truncate
* Purpose: Truncate a string to a certain length if necessary,
* optionally splitting in the middle of a word, and
* appending the $etc string.
* -------------------------------------------------------------
*/
function smarty_modifier_truncate($string, $length = 80, $etc = '...',
$break_words = false)
{
if ($length == 0)
return '';
if (strlen($string) > $length) {
$length -= strlen($etc);
$fragment = substr($string, 0, $length+1);
if ($break_words)
$fragment = substr($fragment, 0, -1);
else
$fragment = preg_replace('/\s+(\S+)?$/', '', $fragment);
return $fragment.$etc;
} else
return $string;
}
?>
]]>
</programlisting>
</example>
</sect1>
<sect1 id="plugins.block.functions"><title>Block Functions</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>smarty_block_<replaceable>name</replaceable></function></funcdef>
<paramdef>array <parameter>$params</parameter></paramdef>
<paramdef>mixed <parameter>$content</parameter></paramdef>
<paramdef>object <parameter>&amp;$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
Block functions are functions of the form: {func} .. {/func}. In other
words, they enclose a template block and operate on the contents of
this block. Block functions take precedence over custom functions of
the same name, that is, you cannot have both custom function {func} and
block function {func} .. {/func}.
</para>
<para>
By default your function implementation is called twice by
Smarty: once for the opening tag, and once for the closing tag
(see <literal>&amp;$repeat</literal> below how to change this).
</para>
<para>
Only the opening tag of the block function may have attributes. All
attributes passed to template functions from the template are contained
in the <parameter>$params</parameter> as an associative array. You can
access those values as e.g. <varname>$params['start']</varname>.
The opening tag attributes are also accessible to your function
when processing the closing tag.
</para>
<para>
The value of <parameter>$content</parameter> variable depends on
whether your function is called for the opening or closing tag. In case
of the opening tag, it will be <literal>null</literal>, and in case of
the closing tag it will be the contents of the template block.
Note that the template block will have already been processed by
Smarty, so all you will receive is the template output, not the
template source.
</para>
<para>
The parameter <parameter>&amp;$repeat</parameter> is passed by
reference to the function implementation and provides a
possibility for it to control how many times the block is
displayed. By default <parameter>$repeat</parameter> is
<literal>true</literal> at the first call of the block-function
(the block opening tag) and <literal>false</literal> on all
subsequent calls to the block function (the block's closing tag).
Each time the function implementation returns with
<parameter>&amp;$repeat</parameter> being true, the contents between
{func} .. {/func} are evaluated and the function implementation
is called again with the new block contents in the parameter
<parameter>$content</parameter>.
</para>
<para>
If you have nested block functions, it's possible to find out what the
parent block function is by accessing
<varname>$smarty->_tag_stack</varname> variable. Just do a var_dump()
on it and the structure should be apparent.
</para>
<para>
See also:
<link linkend="api.register.block">register_block()</link>,
<link linkend="api.unregister.block">unregister_block()</link>.
</para>
<example>
<title>block function</title>
<programlisting role="php">
<![CDATA[
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: block.translate.php
* Type: block
* Name: translate
* Purpose: translate a block of text
* -------------------------------------------------------------
*/
function smarty_block_translate($params, $content, &amp;$smarty)
{
if (isset($content)) {
$lang = $params['lang'];
// do some intelligent translation thing here with $content
return $translation;
}
}
?>
]]>
</programlisting>
</example>
</sect1>
<sect1 id="plugins.compiler.functions"><title>Compiler Functions</title>
<para>
Compiler functions are called only during compilation of the template.
They are useful for injecting PHP code or time-sensitive static
content into the template. If there is both a compiler function and a
custom function registered under the same name, the compiler function
has precedence.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>smarty_compiler_<replaceable>name</replaceable></function></funcdef>
<paramdef>string <parameter>$tag_arg</parameter></paramdef>
<paramdef>object <parameter>&amp;$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 role="php">
<![CDATA[
<?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, &amp;$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 role="php">
<![CDATA[
<?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>&amp;$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>&amp;$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 role="php">
<![CDATA[
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: prefilter.pre01.php
* Type: prefilter
* Name: pre01
* Purpose: Convert html tags to be lowercase.
* -------------------------------------------------------------
*/
function smarty_prefilter_pre01($source, &amp;$smarty)
{
return preg_replace('!<(\w+)[^>]+>!e', 'strtolower("$1")', $source);
}
?>
]]>
</programlisting>
</example>
<para></para>
<example>
<title>postfilter plugin</title>
<programlisting role="php">
<![CDATA[
<?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, &amp;$smarty)
{
$compiled = "<pre>\n<?php print_r(\$this->get_template_vars()); ?>\n</pre>" . $compiled;
return $compiled;
}
?>
]]>
</programlisting>
</example>
</sect1>
<sect1 id="plugins.outputfilters"><title>Output Filters</title>
<para>
Output filter plugins operate on a template's output, after the
template is loaded and executed, but before the output is displayed.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>smarty_outputfilter_<replaceable>name</replaceable></function></funcdef>
<paramdef>string <parameter>$template_output</parameter></paramdef>
<paramdef>object <parameter>&amp;$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The first parameter to the output filter function is the template
output that needs to be processed, and the second parameter is the
instance of Smarty invoking the plugin. The plugin is supposed to do
the processing and return the results.
</para>
<example>
<title>output filter plugin</title>
<programlisting role="php">
<![CDATA[
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: outputfilter.protect_email.php
* Type: outputfilter
* Name: protect_email
* Purpose: Converts @ sign in email addresses to %40 as
* a simple protection against spambots
* -------------------------------------------------------------
*/
function smarty_outputfilter_protect_email($output, &amp;$smarty)
{
return preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
'$1%40$2', $output);
}
?>
]]>
</programlisting>
</example>
</sect1>
<sect1 id="plugins.resources"><title>Resources</title>
<para>
Resource plugins are meant as a generic way of providing template
sources or PHP script components to Smarty. Some examples of resources:
databases, LDAP, shared memory, sockets, and so on.
</para>
<para>
There are a total of 4 functions that need to be registered for each
type of resource. Every function will receive the requested resource as
the first parameter and the Smarty object as the last parameter. The
rest of parameters depend on the function.
</para>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_source</function></funcdef>
<paramdef>string <parameter>$rsrc_name</parameter></paramdef>
<paramdef>string <parameter>&amp;$source</parameter></paramdef>
<paramdef>object <parameter>&amp;$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>&amp;$timestamp</parameter></paramdef>
<paramdef>object <parameter>&amp;$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>&amp;$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>&amp;$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 role="php">
<![CDATA[
<?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
}
?>
]]>
</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>&amp;$smarty</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
The first parameter to the function is an associative array of
attributes passed to the insert.
</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 role="php">
<![CDATA[
<?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;
}
?>
]]>
</programlisting>
</example>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

48
docs/en/programmers/smarty-constants.xml Normal file
View File

@@ -0,0 +1,48 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
<chapter id="smarty.constants">
<title>Constants</title>
<sect1 id="constant.smarty.dir">
<title>SMARTY_DIR</title>
<para>
This should be the full system path to the location of the Smarty
class files. If this is not defined, then Smarty will attempt to
determine the appropriate value automatically. If defined, the path
must end with a slash.
</para>
<example>
<title>SMARTY_DIR</title>
<programlisting role="php">
<![CDATA[
<?php
// set path to Smarty directory
define("SMARTY_DIR","/usr/local/lib/php/Smarty/");
require_once(SMARTY_DIR."Smarty.class.php");
?>
]]>
</programlisting>
</example>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->