smarty/docs/en/programmers/caching/caching-setting-up.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
  <sect1 id="caching.setting.up">
   <title>Setting Up Caching</title>
   <para>
    The first thing to do is enable caching  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
     <link linkend="variable.cache.dir">$cache_dir</link>
     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
    <link linkend="variable.caching">$caching</link> = 2.
    See <link
    linkend="variable.cache.lifetime">$cache_lifetime</link> for more 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
    <link linkend="variable.compile.check">$compile_check</link>
    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.
    <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> = 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 
    <link    linkend="language.function.insert">{insert}</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.
   </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>
    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>

<!-- 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
-->