smarty/docs/en/programmers/plugins/plugins-resources.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
   <sect1 id="plugins.resources"><title>Resources</title>
    <para>
     Resource plugins are meant as a generic way of providing template
     sources or PHP script components to Smarty. Some examples of resources:
     databases, LDAP, shared memory, sockets, and so on.
    </para>

    <para>
     There are a total of four functions that need to be registered for each
     type of resource. Every function will receive the requested resource as
     the first parameter and the Smarty object as the last parameter. The
     rest of parameters depend on the function.
    </para>

    <funcsynopsis>
     <funcprototype>
      <funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_source</function></funcdef>
      <paramdef>string <parameter>$rsrc_name</parameter></paramdef>
      <paramdef>string <parameter>&amp;$source</parameter></paramdef>
      <paramdef>object <parameter>&amp;$smarty</parameter></paramdef>
     </funcprototype>
     <funcprototype>
      <funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_timestamp</function></funcdef>
      <paramdef>string <parameter>$rsrc_name</parameter></paramdef>
      <paramdef>int <parameter>&amp;$timestamp</parameter></paramdef>
      <paramdef>object <parameter>&amp;$smarty</parameter></paramdef>
     </funcprototype>
     <funcprototype>
      <funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_secure</function></funcdef>
      <paramdef>string <parameter>$rsrc_name</parameter></paramdef>
      <paramdef>object <parameter>&amp;$smarty</parameter></paramdef>
     </funcprototype>
     <funcprototype>
      <funcdef>bool <function>smarty_resource_<replaceable>name</replaceable>_trusted</function></funcdef>
      <paramdef>string <parameter>$rsrc_name</parameter></paramdef>
      <paramdef>object <parameter>&amp;$smarty</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>

	<itemizedlist>
	<listitem><para>
     The first function, <literal>source()</literal> is supposed to retrieve
     the resource. Its second parameter <parameter>$source</parameter> is a
     variable passed by reference where the result should be
     stored. The function is supposed to return &true; if
     it was able to successfully retrieve the resource and &false; otherwise.
    </para></listitem>

    <listitem><para>
     The second function, <literal>timestamp()</literal> is supposed to
     retrieve the last modification time of the requested resource, as a UNIX
     timestamp. The second parameter <parameter>$timestamp</parameter>
     is a variable passed by reference where the timestamp should be stored.
     The function is supposed to return &true; if the timestamp could be
     succesfully determined, or &false; otherwise.
    </para></listitem>

    <listitem><para>
     The third function, <literal>secure()</literal>is supposed to return
     &true; or &false;, depending on whether the requested resource is secure
     or not. This function is used only for template resources but
     should still be defined.
    </para></listitem>

    <listitem><para>
     The fourth function, <literal>trusted()</literal> is supposed to return
     &true; or &false;, depending on whether the requested resource
     is trusted or not. This function is used for only for PHP script
     components requested by <link linkend="language.function.include.php">
     <varname>{include_php}</varname></link> tag or
     <link linkend="language.function.insert"><varname>{insert}</varname></link>
     tag with the <parameter>src</parameter> attribute. However, it should still
     be defined even for template resources.
    </para></listitem>
    </itemizedlist>


    <example>
     <title>resource plugin</title>
     <programlisting role="php">
<![CDATA[
<?php
/*
 * Smarty plugin
 * -------------------------------------------------------------
 * File:     resource.db.php
 * Type:     resource
 * Name:     db
 * Purpose:  Fetches templates from a database
 * -------------------------------------------------------------
 */
function smarty_resource_db_source($tpl_name, &$tpl_source, &$smarty)
{
    // do database call here to fetch your template,
    // populating $tpl_source
    $sql = new SQL;
    $sql->query("select tpl_source
                   from my_table
                  where tpl_name='$tpl_name'");
    if ($sql->num_rows) {
        $tpl_source = $sql->record['tpl_source'];
        return true;
    } else {
        return false;
    }
}

function smarty_resource_db_timestamp($tpl_name, &$tpl_timestamp, &$smarty)
{
    // do database call here to populate $tpl_timestamp.
    $sql = new SQL;
    $sql->query("select tpl_timestamp
                   from my_table
                  where tpl_name='$tpl_name'");
    if ($sql->num_rows) {
        $tpl_timestamp = $sql->record['tpl_timestamp'];
        return true;
    } else {
        return false;
    }
}

function smarty_resource_db_secure($tpl_name, &$smarty)
{
    // assume all templates are secure
    return true;
}

function smarty_resource_db_trusted($tpl_name, &$smarty)
{
    // not used for templates
}
?>
]]>
     </programlisting>
    </example>

 <para>
 See also
 <link linkend="api.register.resource"><varname>register_resource()</varname></link>,
 <link linkend="api.unregister.resource"><varname>unregister_resource()</varname></link>.
</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
-->