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
$default_resource_type
is assumed.
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 (no leading slash.)
Example 15.17. Using templates from the $template_dir
<?php $smarty->display('index.tpl'); $smarty->display('file:index.tpl'); // same as above ?>
From within a Smarty template
{include file='index.tpl'} {include file='file:index.tpl'} {* same as above *}
Templates outside of the
$template_dir
require the file:
template resource type, followed by
the absolute path to the template (with leading slash.)
With security enabled, access to templates outside of the template_dir is not allowed.
Example 15.18. Using templates from any directory
<?php $smarty->display('file:/export/templates/index.tpl'); $smarty->display('file:/path/to/my/templates/menu.tpl'); ?>
And from within a Smarty template:
{include file='file:/usr/local/share/templates/navigation.tpl'}
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.
Example 15.19. Using templates from windows file paths
<?php $smarty->display('file:C:/export/templates/index.tpl'); $smarty->display('file:F:/path/to/my/templates/menu.tpl'); ?>
And from within Smarty template:
{include file='file:D:/usr/local/share/templates/navigation.tpl'}
Smarty can render templates from a string by using the string:
or eval:
resource.
The string:
resource behaves much the same as a template file. The template source is compiled from a string and stores the compiled template code for later reuse. Each unique template string will create a new compiled template file. If your template strings are accessed frequently, this is a good choice. If you have frequently changing template strings (or strings with low reuse value), the eval:
resource may be a better choice.
The eval:
resource evaluates the template source every time a page is rendered. This is a good choice
for strings with low reuse value. If the same string is accessed frequently, the string:
resource may
be a better choice.
With a string:
resource type, each unique string generates a compiled file. Smarty cannot detect a string that has changed,
and therefore will generate a new compiled file for each unique string. It is important to choose the correct resource so that you do not
fill your disk space with wasted compiled strings.
Example 15.20. Using templates from strings
<?php $smarty->assign('foo','value'); $template_string = 'display {$foo} here'; $smarty->display('string:'.$template_string); // compiles for later reuse $smarty->display('eval:'.$template_string); // compiles every time ?>
From within a Smarty template
{include file="string:$template_string"} {* compiles for later reuse *} {include file="eval:$template_string"} {* compiles every time *}
The extends:
resource is used to define child/parent relationships for template inheritance from the PHP script.
For details see section of Template Interitance.
Example 15.21. Using template inheritance from the PHP script
<?php $smarty->display('extends:parent.tpl|child.tpl|grandchild.tpl'); ?>
Use this when inheritance is required programatically. When inheriting within PHP, it is not obvious from the child template what inheritance took place. If you have a choice, it is normally more flexible and intuitive to handle inheritance chains from within the templates.
You can retrieve templates using whatever possible source you can access with PHP: databases, sockets, files, etc. You do this by writing resource plugin functions and registering them with Smarty.
See resource plugins section for more information on the functions you are supposed to provide.
Note that you cannot override the built-in
file:
resource, but you can provide a resource
that fetches templates from the file system in some other way by
registering under another resource name.
Example 15.22. Using custom resources
<?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 with actual template contents $tpl_source = "This is the template text"; // return true on success, false to generate failure notification return true; } function db_get_timestamp($tpl_name, &$tpl_timestamp, $smarty_obj) { // do database call here to populate $tpl_timestamp // with unix epoch time value of last template modification. // This is used to determine if recompile is necessary. $tpl_timestamp = time(); // this example will always recompile! // return true on success, false to generate failure notification return true; } 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"); ?>
And from within Smarty template:
{include file='db:/extras/navigation.tpl'}
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.
Example 15.23. Using the default template handler function
<?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."; require_once SMARTY_CORE_DIR . 'core.write_file.php'; smarty_core_write_file( array( 'filename'=>$smarty_obj->template_dir . DIRECTORY_SEPARATOR . $resource_name, 'contents'=>$template_source ), $smarty_obj ); return true; } } else { // not a file return false; } } // set the default handler $smarty->default_template_handler_func = 'make_template'; ?>
See also
Streams