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

Tidy up of formatting

Browse Source
This commit is contained in:
pete_morgan
2006-09-27 00:54:40 +00:00
parent c9bdfdf1e5
commit 782bd58ba0
4 changed files with 159 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/en/programmers/caching/caching-cacheable.xml
View File

@@ -4,22 +4,23 @@
<title>Controlling Cacheability of Plugins' Output</title> <title>Controlling Cacheability of Plugins' Output</title>
<para> <para>
Since Smarty-2.6.0 plugins the cacheability of plugins can be Since Smarty-2.6.0 plugins the cacheability of plugins can be
declared when registering them. The third parameter to <link declared when registering them. The third parameter to
linkend="api.register.block">register_block()</link>, <link <link linkend="api.register.block"><varname>register_block()</varname></link>,
linkend="api.register.compiler.function">register_compiler_function() <link linkend="api.register.compiler.function">
</link> and <link <varname>register_compiler_function()</varname></link> and <link
linkend="api.register.function">register_function()</link> is linkend="api.register.function"><varname>register_function()</varname></link>
called <parameter>$cacheable</parameter> and defaults to true which is called <parameter>$cacheable</parameter> and defaults to &true; which
is also the behaviour of plugins in Smarty versions before 2.6.0 is also the behaviour of plugins in Smarty versions before 2.6.0
</para> </para>
<para> <para>
When registering a plugin with $cacheable=false the plugin is When registering a plugin with <literal>$cacheable=false</literal> the plugin
called everytime the page is displayed, even if the page comes is called everytime the page is displayed, even if the page comes
from the cache. The plugin function behaves a little like an from the cache. The plugin function behaves a little like an
<link linkend="plugins.inserts">insert</link> function. <link linkend="plugins.inserts"><varname>{insert}</varname></link> function.
</para> </para>
<para> <para>
In contrast to <link linkend="plugins.inserts">insert</link> In contrast to <link linkend="plugins.inserts"><varname>{insert}</varname>
</link>
the attributes to the plugins are not cached by default. They can be the attributes to the plugins are not cached by default. They can be
declared to be cached with the fourth parameter declared to be cached with the fourth parameter
<parameter>$cache_attrs</parameter>. <parameter>$cache_attrs</parameter> <parameter>$cache_attrs</parameter>. <parameter>$cache_attrs</parameter>
@@ -33,8 +34,6 @@
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true; $smarty->caching = true;
function remaining_seconds($params, &$smarty) { function remaining_seconds($params, &$smarty) {
@@ -58,7 +57,7 @@ $smarty->display('index.tpl');
]]> ]]>
</programlisting> </programlisting>
<para> <para>
where index.tpl is: where <filename>index.tpl</filename> is:
</para> </para>
<programlisting> <programlisting>
<![CDATA[ <![CDATA[
@@ -66,8 +65,8 @@ Time Remaining: {remaining endtime=$obj->endtime}
]]> ]]>
</programlisting> </programlisting>
<para> <para>
The number of seconds till the endtime of $obj is reached changes on The number of seconds till the endtime of <literal>$obj</literal> is reached
each display of the page, even if the page is cached. Since the 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 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 database when page is written to the cache but not on subsequent requests
of the page. of the page.
@@ -81,9 +80,7 @@ Time Remaining: {remaining endtime=$obj->endtime}
index.php: index.php:
<?php <?php
require('Smarty.class.php'); $smarty->caching = 1;
$smarty = new Smarty;
$smarty->caching = true;
function smarty_block_dynamic($param, $content, &$smarty) { function smarty_block_dynamic($param, $content, &$smarty) {
return $content; return $content;
@@ -95,15 +92,15 @@ $smarty->display('index.tpl');
]]> ]]>
</programlisting> </programlisting>
<para> <para>
where index.tpl is: where <filename>index.tpl</filename> is:
</para> </para>
<programlisting> <programlisting>
<![CDATA[ <![CDATA[
Page created: {"0"|date_format:"%D %H:%M:%S"} Page created: {'0'|date_format:'%D %H:%M:%S'}
{dynamic} {dynamic}
Now is: {"0"|date_format:"%D %H:%M:%S"} Now is: {'0'|date_format:'%D %H:%M:%S'}
... do other stuff ... ... do other stuff ...
@@ -114,9 +111,9 @@ Now is: {"0"|date_format:"%D %H:%M:%S"}
<para> <para>
When reloading the page you will notice that both dates differ. One When reloading the page you will notice that both dates differ. One
is "dynamic" one is "static". You can do everything between is <quote>dynamic</quote> one is <quote>static</quote>. You can do everything
{dynamic}...{/dynamic} and be sure it will not be cached like the rest between <literal>{dynamic}...{/dynamic}</literal> and be sure it will not
of the page. be cached like the rest of the page.
</para> </para>
</sect1> </sect1>

64
docs/en/programmers/caching/caching-groups.xml
View File

@@ -3,37 +3,63 @@
<sect1 id="caching.groups"> <sect1 id="caching.groups">
<title>Cache Groups</title> <title>Cache Groups</title>
<para> <para>
You can do more elaborate grouping by setting up $cache_id groups. This is You can do more elaborate grouping by setting up
accomplished by separating each sub-group with a vertical bar "|" in the <parameter>$cache_id</parameter> groups. This is
$cache_id value. You can have as many sub-groups as you like. accomplished by separating each sub-group with a vertical bar
<literal>|</literal> in the <parameter>$cache_id</parameter> value.
You can have as many sub-groups as you like.
</para> </para>
<para>
<itemizedlist>
<listitem><para>
You can think of cache groups like a directory hierarchy. For instance, a You can think of cache groups like a directory hierarchy. For instance, a
cache group of "a|b|c" could be thought of as the directory structure cache group of <literal>'a|b|c'</literal> could be thought of as the
"/a/b/c/". <link linkend="api.clear.cache">clear_cache</link>(null,"a|b|c") directory structure <literal>'/a/b/c/'</literal>.
</para></listitem>
<listitem><para>
<literal>clear_cache(null,'a|b|c')</literal>
would be like removing the files would be like removing the files
"/a/b/c/*". clear_cache(null,"a|b") would be like removing the files <literal>'/a/b/c/*'</literal>. <literal>clear_cache(null,'a|b')</literal>
"/a/b/*". If you specify a <link linkend="variable.compile.id">$compile_id</link> such as would be like removing the files <literal>'/a/b/*'</literal>.
clear_cache(null,"a|b","foo") it is treated as an appended cache group </para></listitem>
"/a/b/c/foo/". If you specify a template name such as
clear_cache("foo.tpl","a|b|c") then Smarty will attempt to remove <listitem><para>
"/a/b/c/foo.tpl". You CANNOT remove a specified template name under If you specify a
multiple cache groups such as "/a/b/*/foo.tpl", the cache grouping works <link linkend="variable.compile.id"><parameter>$compile_id</parameter></link>
such as <literal>clear_cache(null,'a|b','foo')</literal> it is treated as
an appended cache group <literal>'/a/b/c/foo/'</literal>.
</para></listitem>
<listitem><para>
If you specify a template name such as
<literal>clear_cache('foo.tpl','a|b|c')</literal> then Smarty will attempt
to remove <literal>'/a/b/c/foo.tpl'</literal>.
</para></listitem>
<listitem><para>
You CANNOT remove a specified template name under
multiple cache groups such as <literal>'/a/b/*/foo.tpl'</literal>, the
cache grouping works
left-to-right ONLY. You will need to group your templates under a single left-to-right ONLY. You will need to group your templates under a single
cache group heirarchy to be able to clear them as a group. cache group heirarchy to be able to clear them as a group.
</para> </para></listitem>
</itemizedlist>
<para> <para>
Cache grouping should not be confused with your template directory Cache grouping should not be confused with your template directory
heirarchy, the cache grouping has no knowledge of how your templates are heirarchy, the cache grouping has no knowledge of how your templates are
structured. So for example, if you have a template structure like structured. So for example, if you have a template structure like
"themes/blue/index.tpl" and you want to be able to clear all the cache <filename>themes/blue/index.tpl</filename> and you want to be able to
files for the "blue" theme, you will need to create a cache group clear all the cache files for the <quote>blue</quote> theme, you will need
to create a cache group
structure that mimics your template file structure, such as structure that mimics your template file structure, such as
display("themes/blue/index.tpl","themes|blue"), then clear them with <literal>display('themes/blue/index.tpl','themes|blue')</literal>, then
clear_cache(null,"themes|blue"). clear them with
<literal>clear_cache(null,'themes|blue')</literal>.
</para> </para>
<example> <example>
<title>cache_id groups</title> <title>$cache_id groups</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php

69
docs/en/programmers/caching/caching-multiple-caches.xml
View File

@@ -4,22 +4,23 @@
<title>Multiple Caches Per Page</title> <title>Multiple Caches Per Page</title>
<para> <para>
You can have multiple cache files for a single call to You can have multiple cache files for a single call to
<link linkend="api.display">display()</link> <link linkend="api.display"><varname>display()</varname></link>
or <link linkend="api.fetch">fetch()</link>. or <link linkend="api.fetch"><varname>fetch()</varname></link>.
Let's say that a call to display('index.tpl') may have several Let's say that a call to <literal>display('index.tpl')</literal> may have
different output contents depending on some condition, and you want 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 separate caches for each one. You can do this by passing a
second parameter to the function call. <parameter>$cache_id</parameter> as the second parameter to the
function call.
</para> </para>
<example> <example>
<title>passing a $cache_id to display()</title> <title>Passing a $cache_id to display()</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
require('Smarty.class.php'); require('Smarty.class.php');
$smarty = new Smarty; $smarty = new Smarty;
$smarty->caching = true; $smarty->caching = 1;
$my_cache_id = $_GET['article_id']; $my_cache_id = $_GET['article_id'];
@@ -29,42 +30,45 @@ $smarty->display('index.tpl',$my_cache_id);
</programlisting> </programlisting>
</example> </example>
<para> <para>
Above, we are passing the variable $my_cache_id to Above, we are passing the variable <literal>$my_cache_id</literal> to
<link linkend="api.display">display()</link> <link linkend="api.display"><varname>display()</varname></link>
as the as the <parameter>$cache_id</parameter>. For each unique value of
cache_id. For each unique value of $my_cache_id, a separate cache will be <literal>$my_cache_id</literal>, a separate cache will be
generated for index.tpl. In this example, "article_id" was passed in the generated for <filename>index.tpl</filename>. In this example,
URL and is used as the cache_id. <literal>article_id</literal> was passed in the
URL and is used as the <parameter>$cache_id</parameter>.
</para> </para>
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
<para> <para>
Be very cautious when passing values from a client (web browser) into Be very cautious when passing values from a client (web browser) into
Smarty (or any PHP application.) Although the above example of using the 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 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 <parameter>$cache_id</parameter> 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 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 that sends random article_id's at a rapid pace, this could possibly cause
problems at the server level. Be sure to sanitize any data passed in before 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 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 ten characters and is made up of alpha-numerics only, and must be a valid
article_id in the database. Check for this! article_id in the database. Check for this!
</para> </para>
</note> </note>
<para> <para>
Be sure to pass the same cache_id as the Be sure to pass the same <parameter>$cache_id</parameter> as the
second parameter to <link linkend="api.is.cached">is_cached()</link> and second parameter to
<link linkend="api.clear.cache">clear_cache()</link>. <link linkend="api.is.cached"><varname>is_cached()</varname></link> and
<link linkend="api.clear.cache"><varname>clear_cache()</varname></link>.
</para> </para>
<example> <example>
<title>passing a cache_id to is_cached()</title> <title>Passing a cache_id to is_cached()</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
require('Smarty.class.php'); require('Smarty.class.php');
$smarty = new Smarty; $smarty = new Smarty;
$smarty->caching = true; $smarty->caching = 1;
$my_cache_id = $_GET['article_id']; $my_cache_id = $_GET['article_id'];
@@ -80,31 +84,32 @@ $smarty->display('index.tpl',$my_cache_id);
</programlisting> </programlisting>
</example> </example>
<para> <para>
You can clear all caches for a particular cache_id by passing null as the You can clear all caches for a particular <parameter>$cache_id</parameter>
by passing &null; as the
first parameter to first parameter to
<link linkend="api.clear.cache">clear_cache()</link>. <link linkend="api.clear.cache"><varname>clear_cache()</varname></link>.
</para> </para>
<example> <example>
<title>clearing all caches for a particular cache_id</title> <title>Clearing all caches for a particular $cache_id</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
require('Smarty.class.php'); require('Smarty.class.php');
$smarty = new Smarty; $smarty = new Smarty;
$smarty->caching = true; $smarty->caching = 1;
// clear all caches with "sports" as the cache_id // clear all caches with "sports" as the $cache_id
$smarty->clear_cache(null,"sports"); $smarty->clear_cache(null,'sports');
$smarty->display('index.tpl',"sports"); $smarty->display('index.tpl','sports');
?> ?>
]]> ]]>
</programlisting> </programlisting>
</example> </example>
<para> <para>
In this manner, you can "group" your caches together by giving them the In this manner, you can <quote>group</quote> your caches together by giving
same cache_id. them the same <parameter>$cache_id</parameter>.
</para> </para>
</sect1> </sect1>

93
docs/en/programmers/caching/caching-setting-up.xml
View File

@@ -4,10 +4,11 @@
<title>Setting Up Caching</title> <title>Setting Up Caching</title>
<para> <para>
The first thing to do is enable caching by setting <link The first thing to do is enable caching by setting <link
linkend="variable.caching">$caching</link> = 1 (or 2). linkend="variable.caching">
<parameter>$caching</parameter></link><literal> = 1 (or 2)</literal>.
</para> </para>
<example> <example>
<title>enabling caching</title> <title>Enabling caching</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
@@ -22,34 +23,37 @@ $smarty->display('index.tpl');
</programlisting> </programlisting>
</example> </example>
<para> <para>
With caching enabled, the function call to display('index.tpl') will render With caching enabled, the function call to
<literal>display('index.tpl')</literal> will render
the template as usual, but also saves a copy of its output to a file (a 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>. cached copy) in the
Upon the next call to display('index.tpl'), the cached copy will be used <link linkend="variable.cache.dir"><parameter>$cache_dir</parameter></link>.
instead of rendering the template again. On the next call to <literal>display('index.tpl')</literal>, the cached copy
will be used instead of rendering the template again.
</para> </para>
<note> <note>
<title>Technical Note</title> <title>Technical Note</title>
<para> <para>
The files in the The files in the
<link linkend="variable.cache.dir">$cache_dir</link> <link linkend="variable.cache.dir"><parameter>$cache_dir</parameter></link>
are named similar to the template name. are named similar to the template name.
Although they end in the ".php" extention, they are not intended to be Although they end in the <filename>.php</filename> extention, they are not
directly executable. Do not edit these files! intended to be directly executable. Do not edit these files!
</para> </para>
</note> </note>
<para> <para>
Each cached page has a limited lifetime determined by <link Each cached page has a limited lifetime determined by <link
linkend="variable.cache.lifetime">$cache_lifetime</link>. The default value linkend="variable.cache.lifetime"><parameter>$cache_lifetime</parameter></link>.
is 3600 seconds, or 1 hour. After that time expires, the cache is The default value is 3600 seconds ie an hour. After that time expires, the
regenerated. It is possible to give individual caches their own expiration cache is regenerated. It is possible to give individual caches their own
time by setting expiration time by setting
<link linkend="variable.caching">$caching</link> = 2. <link linkend="variable.caching"><parameter>$caching</parameter></link><literal>=2</literal>.
See <link See <link
linkend="variable.cache.lifetime">$cache_lifetime</link> for more details. linkend="variable.cache.lifetime"><parameter>$cache_lifetime</parameter></link>
for more details.
</para> </para>
<example> <example>
<title>setting $cache_lifetime per cache</title> <title>Setting $cache_lifetime per cache</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
@@ -77,16 +81,17 @@ $smarty->display('home.tpl');
</programlisting> </programlisting>
</example> </example>
<para> <para>
If <link linkend="variable.compile.check">$compile_check</link> is enabled, If <link linkend="variable.compile.check">
<parameter>$compile_check</parameter></link> is enabled,
every template file and config file that is involved with the cache file is 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 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 cache was generated, the cache is immediately regenerated. This is a slight
overhead so for optimum performance, set overhead so for optimum performance, set
<link linkend="variable.compile.check">$compile_check</link> <link linkend="variable.compile.check"><parameter>$compile_check</parameter>
to false. </link> to &false;.
</para> </para>
<example> <example>
<title>enabling $compile_check</title> <title>Enabling $compile_check</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
@@ -102,25 +107,26 @@ $smarty->display('index.tpl');
</programlisting> </programlisting>
</example> </example>
<para> <para>
If <link linkend="variable.force.compile">$force_compile</link> is enabled, If <link linkend="variable.force.compile">
<parameter>$force_compile</parameter></link> is enabled,
the cache files will always be regenerated. This effectively turns off the cache files will always be regenerated. This effectively turns off
caching. caching.
<link linkend="variable.force.compile">$force_compile</link> <link linkend="variable.force.compile"><parameter>$force_compile</parameter>
is usually for </link> is usually for
<link <link linkend="chapter.debugging.console">debugging</link>
linkend="chapter.debugging.console">debugging</link> purposes only, a more efficient way of disabling caching is to set <link
purposes only, a more linkend="variable.caching"><parameter>$caching</parameter>
efficient way of disabling caching is to set <link </link><literal> = 0</literal>.
linkend="variable.caching">$caching</link> = 0.
</para> </para>
<para> <para>
The <link linkend="api.is.cached">is_cached()</link> function The <link linkend="api.is.cached"><varname>is_cached()</varname></link>
function
can be used to test if a template has a valid cache or not. If you have a 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 cached template that requires something like a database fetch, you can use
this to skip that process. this to skip that process.
</para> </para>
<example> <example>
<title>using is_cached()</title> <title>Using is_cached()</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
@@ -142,25 +148,28 @@ $smarty->display('index.tpl');
</example> </example>
<para> <para>
You can keep parts of a page dynamic with the <link You can keep parts of a page dynamic with the <link
linkend="language.function.insert">{insert}</link> template function. Let's linkend="language.function.insert"><varname>{insert}</varname></link>
template function. Let's
say the whole page can be cached except for a banner that is displayed down say the whole page can be cached except for a banner that is displayed down
the right side of the page. By using an the side of the page. By using the
<link linkend="language.function.insert">{insert}</link> <link linkend="language.function.insert"><varname>{insert}</varname></link>
function for the banner, you function for the banner, you
can keep this element dynamic within the cached content. See the can keep this element dynamic within the cached content. See the
documentation on <link linkend="language.function.insert">{insert}</link> for documentation on
more details and examples. <link linkend="language.function.insert"><varname>{insert}</varname></link>
for more details and examples.
</para> </para>
<para> <para>
You can clear all the cache files with the <link You can clear all the cache files with the <link
linkend="api.clear.all.cache">clear_all_cache()</link> function, or linkend="api.clear.all.cache"><varname>clear_all_cache()</varname></link>
function, or
individual cache files individual cache files
<link linkend="caching.groups">(or groups)</link> <link linkend="caching.groups">and groups</link>
with the <link with the <link
linkend="api.clear.cache">clear_cache()</link> function. linkend="api.clear.cache"><varname>clear_cache()</varname></link> function.
</para> </para>
<example> <example>
<title>clearing the cache</title> <title>Clearing the cache</title>
<programlisting role="php"> <programlisting role="php">
<![CDATA[ <![CDATA[
<?php <?php
@@ -169,12 +178,12 @@ $smarty = new Smarty;
$smarty->caching = 1; $smarty->caching = 1;
// clear out all cache files
$smarty->clear_all_cache();
// clear only cache for index.tpl // clear only cache for index.tpl
$smarty->clear_cache('index.tpl'); $smarty->clear_cache('index.tpl');
// clear out all cache files
$smarty->clear_all_cache();
$smarty->display('index.tpl'); $smarty->display('index.tpl');
?> ?>
]]> ]]>