mirror of
https://github.com/smarty-php/smarty.git
synced 2025-08-06 03:14:27 +02:00
Tidy up of formatting
This commit is contained in:
pete_morgan
@@ -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>
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,31 +84,32 @@ $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>
|
||||
|
||||
@@ -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
|
||||
linkend="api.clear.all.cache"><varname>clear_all_cache()</varname></link>
|
||||
function, or
|
||||
individual cache files
|
||||
<link linkend="caching.groups">(or groups)</link>
|
||||
<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');
|
||||
?>
|
||||
]]>
|
||||
|
||||
Reference in New Issue
Block a user