smarty/docs/en/programmers/advanced-features/template-resources.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
  <sect1 id="template.resources">
   <title>Resources</title>
   <para>
	   The templates may come from a variety of sources. When you display or fetch
	   a template, or when you include a template from within another template,
	   you supply a resource type, followed by the appropriate path and template
   	name. If a resource is not explicitly given the value of <link
   	linkend="variable.default.resource.type">$default_resource_type</link> is
   	assumed.
   </para>
   <sect2 id="templates.from.template.dir">
    <title>Templates from $template_dir</title>
    <para>
     Templates from the $template_dir do not require a template
     resource, although you can use the file: resource for consistancy.
     Just supply the path to the template you want to use relative to
     the $template_dir root directory.
    </para>
    <example>
     <title>using templates from $template_dir</title>
     <programlisting role="php">
<![CDATA[
<?php
$smarty->display("index.tpl");
$smarty->display("admin/menu.tpl");
$smarty->display("file:admin/menu.tpl"); // same as one above
?>

{* from within Smarty template *}
{include file="index.tpl"}
{include file="file:index.tpl"} {* same as one above *}
]]>
</programlisting>
    </example>
   </sect2>
   <sect2 id="templates.from.any.dir">
    <title>Templates from any directory</title>
    <para>
     Templates outside of the $template_dir require the file: template
     resource type, followed by the absolute path and name of the
     template.
    </para>
    <example>
     <title>using templates from any directory</title>
     <programlisting role="php">
<![CDATA[
<?php
$smarty->display("file:/export/templates/index.tpl");
$smarty->display("file:/path/to/my/templates/menu.tpl");
?>
]]>
     </programlisting>
     <para>
      And from within Smarty template:
     </para>
     <programlisting>
<![CDATA[
{include file="file:/usr/local/share/templates/navigation.tpl"}
]]>
     </programlisting>
    </example>

    <sect3 id="templates.windows.filepath">
     <title>Windows Filepaths</title>
     <para>
      If you are using a Windows machine, filepaths usually include a
      drive letter (C:) at the beginning of the pathname. Be sure to use
      "file:" in the path to avoid namespace conflicts and get the
      desired results.
     </para>
     <example>
      <title>using templates from windows file paths</title>
      <programlisting role="php">
<![CDATA[
<?php
$smarty->display("file:C:/export/templates/index.tpl");
$smarty->display("file:F:/path/to/my/templates/menu.tpl");
?>
]]>
     </programlisting>
     <para>
      And from within Smarty template:
     </para>
     <programlisting>
<![CDATA[
{include file="file:D:/usr/local/share/templates/navigation.tpl"}
]]>
</programlisting>
     </example>
    </sect3>
   </sect2>

   <sect2 id="templates.from.elsewhere">
    <title>Templates from other sources</title>
    <para>
     You can retrieve templates using whatever possible source you can
     access with PHP: databases, sockets, LDAP, and so on. You do this
     by writing resource plugin functions and registering them with
     Smarty.
    </para>

    <para>
     See <link linkend="plugins.resources">resource plugins</link>
     section for more information on the functions you are supposed
     to provide.
    </para>

    <note>
     <para>
      Note that you cannot override the built-in
      <literal>file</literal> resource, but you can provide a resource
      that fetches templates from the file system in some other way by
      registering under another resource name.
     </para>
    </note>
    <example>
     <title>using custom resources</title>
     <programlisting role="php">
<![CDATA[
<?php
// put these function somewhere in your application
function db_get_template ($tpl_name, &$tpl_source, &$smarty_obj)
{
    // 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 db_get_timestamp($tpl_name, &$tpl_timestamp, &$smarty_obj)
{
    // 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 db_get_secure($tpl_name, &$smarty_obj)
{
    // assume all templates are secure
    return true;
}

function db_get_trusted($tpl_name, &$smarty_obj)
{
    // not used for templates
}

// register the resource name "db"
$smarty->register_resource("db", array("db_get_template",
                                       "db_get_timestamp",
                                       "db_get_secure",
                                       "db_get_trusted"));

// using resource from php script
$smarty->display("db:index.tpl");
?>
]]>
     </programlisting>
     <para>
      And from within Smarty template:
     </para>
     <programlisting>
<![CDATA[
{include file="db:/extras/navigation.tpl"}
]]>
     </programlisting>
    </example>
   </sect2>

   <sect2 id="default.template.handler.function">
    <title>Default template handler function</title>
    <para>
     You can specify a function that is used to retrieve template
     contents in the event the template cannot be retrieved from its
     resource. One use of this is to create templates that do not exist
     on-the-fly.
    </para>
    <example>
     <title>using the default template handler function</title>
     <programlisting role="php">
<![CDATA[
<?php
// put this function somewhere in your application

function make_template ($resource_type, $resource_name, &$template_source, &$template_timestamp, &$smarty_obj)
{
	if( $resource_type == 'file' ) {
		if ( ! is_readable ( $resource_name )) {
			// create the template file, return contents.
			$template_source = "This is a new template.";
			$template_timestamp = time();
			$smarty_obj->_write_file($resource_name,$template_source);
			return true;
		}
    } else {
		// not a file
		return false;
    }
}

// set the default handler
$smarty->default_template_handler_func = 'make_template';
?>
]]>
     </programlisting>
    </example>
   </sect2>
  </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
-->