Tidy up of formatting

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

View File

@@ -4,22 +4,23 @@
<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 <link
linkend="api.register.block">register_block()</link>, <link
linkend="api.register.compiler.function">register_compiler_function()
</link> and <link
linkend="api.register.function">register_function()</link> is
called <parameter>$cacheable</parameter> and defaults to true which
declared when registering them. The third parameter to
<link linkend="api.register.block"><varname>register_block()</varname></link>,
<link linkend="api.register.compiler.function">
<varname>register_compiler_function()</varname></link> and <link
linkend="api.register.function"><varname>register_function()</varname></link>
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
When registering a plugin with <literal>$cacheable=false</literal> 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.
<link linkend="plugins.inserts"><varname>{insert}</varname></link> function.
</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
declared to be cached with the fourth parameter
<parameter>$cache_attrs</parameter>. <parameter>$cache_attrs</parameter>
@@ -33,8 +34,6 @@
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
function remaining_seconds($params, &$smarty) {
@@ -58,7 +57,7 @@ $smarty->display('index.tpl');
]]>
</programlisting>
<para>
where index.tpl is:
where <filename>index.tpl</filename> is:
</para>
<programlisting>
<![CDATA[
@@ -66,8 +65,8 @@ Time Remaining: {remaining 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
The number of seconds till the endtime of <literal>$obj</literal> 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.
@@ -81,9 +80,7 @@ Time Remaining: {remaining endtime=$obj->endtime}
index.php:
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->caching = 1;
function smarty_block_dynamic($param, $content, &$smarty) {
return $content;
@@ -95,15 +92,15 @@ $smarty->display('index.tpl');
]]>
</programlisting>
<para>
where index.tpl is:
where <filename>index.tpl</filename> is:
</para>
<programlisting>
<![CDATA[
Page created: {"0"|date_format:"%D %H:%M:%S"}
Page created: {'0'|date_format:'%D %H:%M:%S'}
{dynamic}
Now is: {"0"|date_format:"%D %H:%M:%S"}
Now is: {'0'|date_format:'%D %H:%M:%S'}
... do other stuff ...
@@ -114,9 +111,9 @@ Now is: {"0"|date_format:"%D %H:%M:%S"}
<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.
is <quote>dynamic</quote> one is <quote>static</quote>. You can do everything
between <literal>{dynamic}...{/dynamic}</literal> and be sure it will not
be cached like the rest of the page.
</para>
</sect1>

View File

@@ -3,37 +3,63 @@
<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.
You can do more elaborate grouping by setting up
<parameter>$cache_id</parameter> groups. This is
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>
<itemizedlist>
<listitem><para>
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
"/a/b/c/". <link linkend="api.clear.cache">clear_cache</link>(null,"a|b|c")
cache group of <literal>'a|b|c'</literal> could be thought of as the
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
"/a/b/c/*". clear_cache(null,"a|b") would be like removing the files
"/a/b/*". If you specify a <link linkend="variable.compile.id">$compile_id</link> such as
clear_cache(null,"a|b","foo") it is treated as an appended cache group
"/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
"/a/b/c/foo.tpl". You CANNOT remove a specified template name under
multiple cache groups such as "/a/b/*/foo.tpl", the cache grouping works
<literal>'/a/b/c/*'</literal>. <literal>clear_cache(null,'a|b')</literal>
would be like removing the files <literal>'/a/b/*'</literal>.
</para></listitem>
<listitem><para>
If you specify a
<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
cache group heirarchy to be able to clear them as a group.
</para>
</para></listitem>
</itemizedlist>
<para>
Cache grouping should not be confused with your template directory
heirarchy, the cache grouping has no knowledge of how your templates are
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
files for the "blue" theme, you will need to create a cache group
<filename>themes/blue/index.tpl</filename> and you want to be able to
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
display("themes/blue/index.tpl","themes|blue"), then clear them with
clear_cache(null,"themes|blue").
<literal>display('themes/blue/index.tpl','themes|blue')</literal>, then
clear them with
<literal>clear_cache(null,'themes|blue')</literal>.
</para>
<example>
<title>cache_id groups</title>
<title>$cache_id groups</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -58,7 +84,7 @@ $smarty->display('index.tpl','sports|basketball');
]]>
</programlisting>
</example>
</sect1>
<!-- Keep this comment at the end of the file

View File

@@ -4,67 +4,71 @@
<title>Multiple Caches Per Page</title>
<para>
You can have multiple cache files for a single call to
<link linkend="api.display">display()</link>
or <link linkend="api.fetch">fetch()</link>.
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.
<link linkend="api.display"><varname>display()</varname></link>
or <link linkend="api.fetch"><varname>fetch()</varname></link>.
Let's say that a call to <literal>display('index.tpl')</literal> 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
<parameter>$cache_id</parameter> as the second parameter to the
function call.
</para>
<example>
<title>passing a $cache_id to display()</title>
<title>Passing a $cache_id to display()</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->caching = 1;
$my_cache_id = $_GET['article_id'];
$smarty->display('index.tpl',$my_cache_id);
$smarty->display('index.tpl', $my_cache_id);
?>
]]>
</programlisting>
</example>
<para>
Above, we are passing the variable $my_cache_id to
<link linkend="api.display">display()</link>
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.
Above, we are passing the variable <literal>$my_cache_id</literal> to
<link linkend="api.display"><varname>display()</varname></link>
as the <parameter>$cache_id</parameter>. For each unique value of
<literal>$my_cache_id</literal>, a separate cache will be
generated for <filename>index.tpl</filename>. In this example,
<literal>article_id</literal> was passed in the
URL and is used as the <parameter>$cache_id</parameter>.
</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
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
<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
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
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!
</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>.
Be sure to pass the same <parameter>$cache_id</parameter> as the
second parameter to
<link linkend="api.is.cached"><varname>is_cached()</varname></link> and
<link linkend="api.clear.cache"><varname>clear_cache()</varname></link>.
</para>
<example>
<title>passing a cache_id to is_cached()</title>
<title>Passing a cache_id to is_cached()</title>
<programlisting role="php">
<![CDATA[
<?php
require('Smarty.class.php');
$smarty = new Smarty;
$smarty->caching = true;
$smarty->caching = 1;
$my_cache_id = $_GET['article_id'];
@@ -80,35 +84,36 @@ $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
You can clear all caches for a particular <parameter>$cache_id</parameter>
by passing &null; as the
first parameter to
<link linkend="api.clear.cache">clear_cache()</link>.
<link linkend="api.clear.cache"><varname>clear_cache()</varname></link>.
</para>
<example>
<title>clearing all caches for a particular cache_id</title>
<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;
$smarty->caching = 1;
// clear all caches with "sports" as the cache_id
$smarty->clear_cache(null,"sports");
// clear all caches with "sports" as the $cache_id
$smarty->clear_cache(null,'sports');
$smarty->display('index.tpl',"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.
In this manner, you can <quote>group</quote> your caches together by giving
them the same <parameter>$cache_id</parameter>.
</para>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml

View File

@@ -4,10 +4,11 @@
<title>Setting Up Caching</title>
<para>
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>
<example>
<title>enabling caching</title>
<title>Enabling caching</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -22,34 +23,37 @@ $smarty->display('index.tpl');
</programlisting>
</example>
<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
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.
cached copy) in the
<link linkend="variable.cache.dir"><parameter>$cache_dir</parameter></link>.
On the next call to <literal>display('index.tpl')</literal>, the cached copy
will be used instead of rendering the template again.
</para>
<note>
<title>Technical Note</title>
<para>
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.
Although they end in the ".php" extention, they are not intended to be
directly executable. Do not edit these files!
Although they end in the <filename>.php</filename> extention, they are not
intended to be directly executable. 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
<link linkend="variable.caching">$caching</link> = 2.
linkend="variable.cache.lifetime"><parameter>$cache_lifetime</parameter></link>.
The default value is 3600 seconds ie an hour. After that time expires, the
cache is regenerated. It is possible to give individual caches their own
expiration time by setting
<link linkend="variable.caching"><parameter>$caching</parameter></link><literal>=2</literal>.
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>
<example>
<title>setting $cache_lifetime per cache</title>
<title>Setting $cache_lifetime per cache</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -77,16 +81,17 @@ $smarty->display('home.tpl');
</programlisting>
</example>
<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
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, set
<link linkend="variable.compile.check">$compile_check</link>
to false.
<link linkend="variable.compile.check"><parameter>$compile_check</parameter>
</link> to &false;.
</para>
<example>
<title>enabling $compile_check</title>
<title>Enabling $compile_check</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -102,25 +107,26 @@ $smarty->display('index.tpl');
</programlisting>
</example>
<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
caching.
<link linkend="variable.force.compile">$force_compile</link>
is usually for
<link
linkend="chapter.debugging.console">debugging</link>
purposes only, a more
efficient way of disabling caching is to set <link
linkend="variable.caching">$caching</link> = 0.
<link linkend="variable.force.compile"><parameter>$force_compile</parameter>
</link> is usually for
<link linkend="chapter.debugging.console">debugging</link>
purposes only, a more efficient way of disabling caching is to set <link
linkend="variable.caching"><parameter>$caching</parameter>
</link><literal> = 0</literal>.
</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
cached template that requires something like a database fetch, you can use
this to skip that process.
</para>
<example>
<title>using is_cached()</title>
<title>Using is_cached()</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -142,25 +148,28 @@ $smarty->display('index.tpl');
</example>
<para>
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
the right side of the page. By using an
<link linkend="language.function.insert">{insert}</link>
the side of the page. By using the
<link linkend="language.function.insert"><varname>{insert}</varname></link>
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
more details and examples.
documentation on
<link linkend="language.function.insert"><varname>{insert}</varname></link>
for more 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
<link linkend="caching.groups">(or groups)</link>
linkend="api.clear.all.cache"><varname>clear_all_cache()</varname></link>
function, or
individual cache files
<link linkend="caching.groups">and groups</link>
with the <link
linkend="api.clear.cache">clear_cache()</link> function.
linkend="api.clear.cache"><varname>clear_cache()</varname></link> function.
</para>
<example>
<title>clearing the cache</title>
<title>Clearing the cache</title>
<programlisting role="php">
<![CDATA[
<?php
@@ -169,12 +178,12 @@ $smarty = new Smarty;
$smarty->caching = 1;
// clear out all cache files
$smarty->clear_all_cache();
// clear only cache for index.tpl
$smarty->clear_cache('index.tpl');
// clear out all cache files
$smarty->clear_all_cache();
$smarty->display('index.tpl');
?>
]]>