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

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision$ -->
  <chapter id="advanced.features">
   <title>Advanced Features</title>
   <sect1 id="advanced.features.objects">
    <title>Objects</title>
    <para>
     Smarty allows access to PHP objects through the templates. There are
	 two ways to access them. One way is to register objects to the template,
	 then use access them via syntax similar to custom functions. The other way
	 is to assign objects to the templates and access them much like any other
	 assigned variable. The first method has a much nicer template syntax. It
	 is also more secure, as a registered object can be restricted to certain
	 methods or properties. However, a registered object cannot be looped over
	 or assigned in arrays of objects, etc. The method you choose will be
	 determined by your needs, but use the first method whenever possible to
	 keep template syntax to a minimum.
    </para>
	<para>
    If security is enabled, no private methods or functions can be accessed
	(begininning with "_"). If a method and property of the same name exist,
	the method will be used.
	</para>
	<para>
	You can restrict the methods and properties that can be accessed by
	listing them in an array as the third registration parameter.
	</para>
	<para>
	By default, parameters passed to objects through the templates are passed
	the same way custom functions get them. An associative array is passed
	as the first parameter, and the smarty object as the second. If you want
	the parameters passed one at a time for each argument like traditional
	object parameter passing, set the fourth registration parameter to false.
	</para>
	<para>
	The optional fifth parameter has only effect with
	<parameter>format</parameter> being <literal>true</literal>
	and contains a list ob methods that should be treated as
	blocks. That means these methods have a closing tag in the
	template
	(<literal>{foobar->meth2}...{/foobar->meth2}</literal>) and
	the parameters to the methods have the same synopsis as the
	parameters for block-function-plugins: They get 4 parameters
	<parameter>$params</parameter>,
	<parameter>$content</parameter>,
	<parameter>&amp;$smarty</parameter> and
	<parameter>&amp;$repeat</parameter> and they also behave like
	block-function-plugins.
	</para>
    <example>
     <title>using a registered or assigned object</title>
<programlisting role="php">
<![CDATA[
<?php
// the object

class My_Object {
	function meth1($params, &amp;$smarty_obj) {
		return "this is my meth1";
	}
}

$myobj = new My_Object;
// registering the object (will be by reference)
$smarty->register_object("foobar",$myobj);
// if we want to restrict access to certain methods or properties, list them
$smarty->register_object("foobar",$myobj,array('meth1','meth2','prop1'));
// if you want to use the traditional object parameter format, pass a boolean of false
$smarty->register_object("foobar",$myobj,null,false);

// We can also assign objects. Assign by ref when possible.
$smarty->assign_by_ref("myobj", $myobj);

$smarty->display("index.tpl");
?>

TEMPLATE:

{* access our registered object *}
{foobar->meth1 p1="foo" p2=$bar}

{* you can also assign the output *}
{foobar->meth1 p1="foo" p2=$bar assign="output"}
the output was {$output}

{* access our assigned object *}
{$myobj->meth1("foo",$bar)}
]]>
</programlisting>
    </example>
  </sect1>
   <sect1 id="advanced.features.prefilters">
    <title>Prefilters</title>
    <para>
     Template prefilters are PHP functions that your templates are ran through
     before they are compiled. This is good for preprocessing your templates
     to remove unwanted comments, keeping an eye on what people are putting
     in their templates, etc. Prefilters can be either
     <link linkend="api.register.prefilter">registered</link> or loaded from
     the plugins directory by using
     <link linkend="api.load.filter">load_filter()</link> function or by
     setting
     <link linkend="variable.autoload.filters">$autoload_filters</link> variable.
     Smarty will pass the template source code as the first argument, and
     expect the function to return the resulting template source code.
    </para>
    <example>
     <title>using a template prefilter</title>
<programlisting role="php">
<![CDATA[
<?php
// put this in your application
function remove_dw_comments($tpl_source, &amp;$smarty)
{
    return preg_replace("/<!--#.*-->/U","",$tpl_source);
}

// register the prefilter
$smarty->register_prefilter("remove_dw_comments");
$smarty->display("index.tpl");
?>

{* Smarty template index.tpl *}
<!--# this line will get removed by the prefilter -->
]]>
</programlisting>
    </example>
   </sect1>

   <sect1 id="advanced.features.postfilters">
    <title>Postfilters</title>
    <para>
     Template postfilters are PHP functions that your templates are ran through
     after they are compiled. Postfilters can be either 
     <link linkend="api.register.postfilter">registered</link> or loaded
     from the plugins directory by using
     <link linkend="api.load.filter">load_filter()</link> function or by
     setting
     <link linkend="variable.autoload.filters">$autoload_filters</link>
     variable. Smarty will pass the compiled template code as the first
     argument, and expect the function to return the result of the
     processing.
    </para>
    <example>
     <title>using a template postfilter</title>
     <programlisting role="php">
<![CDATA[
<?php
// put this in your application
function add_header_comment($tpl_source, &amp;$smarty)
{
    return "<?php echo \"<!-- Created by Smarty! -->;\n\" ?>;\n".$tpl_source;
}

// register the postfilter
$smarty->register_postfilter("add_header_comment");
$smarty->display("index.tpl");
?>

{* compiled Smarty template index.tpl *}
<!-- Created by Smarty! -->
{* rest of template content... *}
]]>
</programlisting>
    </example>
  </sect1>

  <sect1 id="advanced.features.outputfilters">
   <title>Output Filters</title>
   <para>
    When the template is invoked via display() or fetch(), its output can be
    sent through one or more output filters. This differs from postfilters
    because postfilters operate on compiled templates before they are saved to
    the disk, and output filters operate on the template output when it is
    executed.
   </para>

   <para>
    Output filters can be either 
    <link linkend="api.register.outputfilter">registered</link> or loaded
    from the plugins directory by using
    <link linkend="api.load.filter">load_filter()</link> function or by
    setting
    <link linkend="variable.autoload.filters">$autoload_filters</link>
    variable. Smarty will pass the template output as the first argument,
    and expect the function to return the result of the processing.
   </para>
   <example>
    <title>using a template outputfilter</title>
    <programlisting role="php">
<![CDATA[
<?php
// put this in your application
function protect_email($tpl_output, &amp;$smarty)
{
    $tpl_output =
       preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
                    '$1%40$2', $tpl_output);
    return $tpl_output;
}

// register the outputfilter
$smarty->register_outputfilter("protect_email");
$smarty->display("index.tpl");

// now any occurrence of an email address in the template output will have
// a simple protection against spambots
?>
]]>
</programlisting>
   </example>
  </sect1>

  <sect1 id="section.template.cache.handler.func">
   <title>Cache Handler Function</title>
   <para>
    As an alternative to using the default file-based caching mechanism, you
    can specify a custom cache handling function that will be used to read,
    write and clear cached files.
   </para>
   <para>
    Create a function in your application that Smarty will use as a
    cache handler. Set the name of it in the
    <link linkend="variable.cache.handler.func">$cache_handler_func</link>
    class variable. Smarty will now use this to handle cached data. The
    first argument is the action, which will be one of 'read', 'write' and
    'clear'. The second parameter is the Smarty object. The third parameter
    is the cached content. Upon a write, Smarty passes the cached content
    in these parameters. Upon a 'read', Smarty expects your function to
    accept this parameter by reference and populate it with the cached
    data. Upon a 'clear', pass a dummy variable here since it is not used.
    The fourth parameter is the name of the template file (needed for
    read/write), the fifth parameter is the cache_id (optional), and the
    sixth is the compile_id (optional).
   </para>
   <para>
    Note: The last parameter ($exp_time) was added in Smarty-2.6.0.
   </para>
   <example>
    <title>example using MySQL as a cache source</title>
    <programlisting role="php">
<![CDATA[
<?php
/*

example usage:

include('Smarty.class.php');
include('mysql_cache_handler.php');

$smarty = new Smarty;
$smarty->cache_handler_func = 'mysql_cache_handler';

$smarty->display('index.tpl');


mysql database is expected in this format:
	
create database SMARTY_CACHE;

create table CACHE_PAGES(
CacheID char(32) PRIMARY KEY,
CacheContents MEDIUMTEXT NOT NULL
);

*/

function mysql_cache_handler($action, &amp;$smarty_obj, &amp;$cache_content, $tpl_file=null, $cache_id=null, $compile_id=null, $exp_time=null)
{
	// set db host, user and pass here
	$db_host = 'localhost';
	$db_user = 'myuser';
	$db_pass = 'mypass';
	$db_name = 'SMARTY_CACHE';
	$use_gzip = false;
	
	// create unique cache id
	$CacheID = md5($tpl_file.$cache_id.$compile_id);
	
	if(! $link = mysql_pconnect($db_host, $db_user, $db_pass)) {
		$smarty_obj->_trigger_error_msg("cache_handler: could not connect to database");
		return false;
	}
	mysql_select_db($db_name);

	switch ($action) {
		case 'read':
			// save cache to database
			$results = mysql_query("select CacheContents from CACHE_PAGES where CacheID='$CacheID'");
			if(!$results) {
				$smarty_obj->_trigger_error_msg("cache_handler: query failed.");			
			}
			$row = mysql_fetch_array($results,MYSQL_ASSOC);
			
			if($use_gzip && function_exists("gzuncompress")) {
				$cache_contents = gzuncompress($row["CacheContents"]);
			} else {
				$cache_contents = $row["CacheContents"];
			}
			$return = $results;
			break;
		case 'write':
			// save cache to database
			
			if($use_gzip && function_exists("gzcompress")) {
				// compress the contents for storage efficiency
				$contents = gzcompress($cache_content);
			} else {
				$contents = $cache_content;
			}
			$results = mysql_query("replace into CACHE_PAGES values(
							'$CacheID',
							'".addslashes($contents)."')
						");
			if(!$results) {
				$smarty_obj->_trigger_error_msg("cache_handler: query failed.");			
			}
			$return = $results;
			break;
		case 'clear':
			// clear cache info
			if(empty($cache_id) && empty($compile_id) && empty($tpl_file)) {
				// clear them all
				$results = mysql_query("delete from CACHE_PAGES");			
			} else {
				$results = mysql_query("delete from CACHE_PAGES where CacheID='$CacheID'");			
			}
			if(!$results) {
				$smarty_obj->_trigger_error_msg("cache_handler: query failed.");			
			}
			$return = $results;
			break;
		default:
			// error, unknown action
			$smarty_obj->_trigger_error_msg("cache_handler: unknown action \"$action\"");
			$return = false;
			break;
	}
	mysql_close($link);
	return $return;
	
}

?>
]]>
</programlisting>
    </example>
  </sect1>

  <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");
?>

{* from within Smarty template *}
{include file="file:/usr/local/share/templates/navigation.tpl"}
]]>
</programlisting>
    </example>

    <sect3>
     <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");
?>

{* from within Smarty template *}
{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, &amp;$tpl_source, &amp;$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, &amp;$tpl_timestamp, &amp;$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, &amp;$smarty_obj)
{
    // assume all templates are secure
    return true;
}

function db_get_trusted($tpl_name, &amp;$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");
?>

{* using resource from within Smarty template *}
{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, &amp;$template_source, &amp;$template_timestamp, &amp;$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>
</chapter>
<!-- 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
-->