smarty/docs/en/programmers/caching/caching-cacheable.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
 <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
   <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 <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"><varname>{insert}</varname></link> function.
  </para>
  <para>
   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>
   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[
<?php
$smarty->caching = true;

function remaining_seconds($params, &$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');
?>
]]>
   </programlisting>
   <para>
    where <filename>index.tpl</filename> is:
   </para>
   <programlisting>
<![CDATA[
Time Remaining: {remaining endtime=$obj->endtime}
]]>
   </programlisting>
   <para>
    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.
   </para>
  </example>

  <example>
   <title>Preventing a whole passage of a template from being cached</title>
   <programlisting role="php">
<![CDATA[
index.php:

<?php
$smarty->caching = 1;

function smarty_block_dynamic($param, $content, &$smarty) {
    return $content;
}
$smarty->register_block('dynamic', 'smarty_block_dynamic', false);

$smarty->display('index.tpl');
?>
]]>
   </programlisting>
   <para>
    where <filename>index.tpl</filename> is:
   </para>
   <programlisting>
<![CDATA[
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 <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>

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