Smarty For ProgrammersVariables$template_dir
This is the name of the default template directory. If you do
not supply a resource type when including files, they will be
found here. By default this is "./templates", meaning that it
will look for the templates directory in the same directory as
the executing php script.
Technical Note
It is not mandatory to put this directory under
the web server document root.
$compile_dir
This is the name of the directory where compiled templates are
located. By default this is "./templates_c", meaning that it
will look for the compile directory in the same directory as
the executing php script. This was added to Smarty version
1.2.1.
Technical Note
This setting must be either a relative or
absolute path. include_path is not used for writing files.
Technical Note
It is not mandatory to put this directory under
the web server document root.
$config_dir
This is the directory used to store config files used in the
templates. Default is "./configs", meaning that it will look
for the configs directory in the same directory as the
executing php script.
Technical Note
It is not mandatory to put this directory under
the web server document root.
$plugins_dir
This is the directory where Smarty will look for the plugins that
it needs. The directory must be relative to the directory where
Smarty itself is installed. Default is "plugins". There can be
only one plugins directory.
$debugging
This enables the debugging console.
The console is a javascript window that informs you of the
included templates and assigned variables for the current
template page.
NOTE: This was added to Smarty 1.4.3.
$debug_tpl
This is the name of the template file used for the debugging
console.
NOTE: This was added to Smarty 1.4.3.
$debugging_ctrl
This allows alternate ways to enable debugging. NONE means no
alternate methods are allowed. URL means when the keyword
SMARTY_DEBUG is found in the QUERY_STRING, debugging is enabled
for that invocation of the script. If $debugging is true, this
value is ignored.
NOTE: This was added to Smarty 1.4.4.
$global_assign
This is a list of variables that are always implicitly assigned
to the template engine. This is handy for making global
variables or server variables available to all templates
without having to manually assign them. Each element in the
$global_assign should be either a name of the global variable,
or a key/value pair, where the key is the name of the global
array and the value is the array of variables to be assigned
from that global array. $SCRIPT_NAME is globally assigned by
default from $HTTP_SERVER_VARS.
Technical Note
Server variables can be accessed through the
$smarty variable, such as {$smarty.server.SCRIPT_NAME}. See the
section on the
$smarty variable.
$undefined
This sets the value of $undefined for Smarty, default is null.
Currently this is only used to set undefined variables in
$global_assign to a default value.
$autoload_filters
If there are some filters that you wish to load on every template
invocation, you can specify them using this variable and Smarty will
automatically load them for you. The variable is an associative array
where keys are filter types and values are arrays of the filter
names. For example:
$smarty->autoload_filters = array('pre' => array('trim', 'stamp'),
'output' => array('convert'));
$compile_check
Upon each invocation of the PHP application, Smarty tests to
see if the current template has changed (later time stamp)
since the last time it was compiled. If it has changed, it
recompiles that template. As of 1.4.0, if the template has not
been compiled, it will compile regardless of this setting. By
default this variable is set to true. Once an application is
put into production (templates won't be changing), the
compile_check step is no longer needed. Be sure to set
$compile_check to "false" to improve performance! Note that if
you change this to "false" and a template file is changed, you
will *not* see the change since the template will not get
recompiled. If caching is enabled and compile_check is enabled,
then the cache files will get regenerated if an involved
template file was updated. See $force_compile or clear_compiled_tpl.
$force_compile
This forces Smarty to (re)compile templates on every
invocation. This setting overrides $compile_check. By default
this is disabled. This is handy for development and debugging.
It should never be used in a production environment. If caching
is enabled, the cache file(s) will be regenerated every time.
$caching
This tells Smarty whether or not to cache the output of the templates.
By default this is set to 0, or disabled. If your templates generate
redundant redundant content, it is advisable to turn on caching. This
will result in significant performance gains. You can also have multiple
caches for the same template. A value of 1 or 2 enables caching. 1 tells
Smarty to use the current $cache_lifetime variable to determine if the
cache has expired. A value of 2 tells Smarty to use the cache_lifetime
value at the time the cache was generated. This way you can set the
cache_lifetime just before fetching the template to have granular
control over when that particular cache expires. See also is_cached.
If $compile_check is enabled, the cached content will be regenerated if
any of the templates or config files that are part of this cache are
changed. If $force_compile is enabled, the cached content will always be
regenerated.
$cache_dir
This is the name of the directory where template caches are
stored. By default this is "./cache", meaning that it will look
for the cache directory in the same directory as the executing
php script. You can also use your own custom cache handler
function to control cache files, which will ignore this
setting. (added to Smarty 1.3.0)
Technical Note
This setting must be either a relative or
absolute path. include_path is not used for writing files.
Technical Note
It is not mandatory to put this directory under
the web server document root.
$cache_lifetime
This is the length of time in seconds that a template cache is valid.
Once this time has expired, the cache will be regenerated. $caching must
be set to "true" for this setting to work. You can also force the cache
to expire with clear_all_cache. A setting of -1
will force the cache to never expire. A setting of 0 will cause the
cache to always regenerate (which doesn't make much sense, you'd be
better off setting caching=false.) If $caching = 2, then the cache
expiration time is saved along with the template.
$cache_handler_func
You can supply a custom function to handle cache files instead
of using the built-in method using the $cache_dir. See the
custom cache handler function section for details.
$cache_modified_check
If set to true, Smarty will respect the If-Modified-Since
header sent from the client. If the cached file timestamp has
not changed since the last visit, then a "304 Not Modified"
header will be sent instead of the content. This works only on
cached content without insert tags.
$default_template_handler_func
This function is called when a template cannot be obtained from
its resource. (added to Smarty 1.5.2)
$php_handling
This tells Smarty how to handle PHP code embedded in the
tempalates. There are four possible settings, default being
SMARTY_PHP_PASSTHRU. Note that this does NOT affect php code
within {php}{/php}
tags in the template.
SMARTY_PHP_PASSTHRU - Smarty echos tags as-is.SMARTY_PHP_QUOTE - Smarty quotes the tags as
html entities.SMARTY_PHP_REMOVE - Smarty removes the tags from
the templates.SMARTY_PHP_ALLOW - Smarty will execute the tags
as PHP code.
NOTE: Embedding PHP code into templates is highly discouraged.
Use custom functions or
modifiers instead.
$security
$security true/false, default is false. Security is good for
situations when you have untrusted parties editing the templates
(via ftp for example) and you want to reduce the risk of system
security compromises through the template language. Turning on
security enforces the following rules to the template language,
unless specifially overridden with $security_settings:
If $php_handling is set to SMARTY_PHP_ALLOW, this is
implicitly changed to SMARTY_PHP_PASSTHRUPHP functions are not allowed in IF statements,
except those specified in the $security_settingstemplates can only be included from directories
listed in the $secure_dir arraylocal files can only be fetched from directories
listed in the $secure_dir array using {fetch}{php}{/php} tags are not allowedPHP functions are not allowed as modifiers, except
those specified in the $security_settings
NOTE: Security features were added to Smarty 1.4.3.
$secure_dir
This is an array of all local directories that are considered
secure. {include} and {fetch} use this when security is enabled.
$security_settings
These are used to override or specify the security settings when
security is enabled. These are the possible settings:
PHP_HANDLING - true/false. If set to true, the
$php_handling setting is not checked for security.IF_FUNCS - This is an array of the names of permitted
PHP functions in IF statements.INCLUDE_ANY - true/false. If set to true, any
template can be included from the file system, regardless of the
$secure_dir list.PHP_TAGS - true/false. If set to true, {php}{/php}
tags are permitted in the templates.MODIFIER_FUNCS - This is an array of the names of permitted
PHP functions used as variable modifiers.$trusted_dir
$trusted_dir is only for use when $security is enabled. This is an array
of all directories that are considered trusted. Trusted directories are
where you keep php scripts that are executed directly from the templates
with {include_php}.
$left_delimiter
This is the left delimiter used by the template language.
Default is "{".
$right_delimiter
This is the right delimiter used by the template language.
Default is "}".
$show_info_header
Shows an HTML comment at the beginning of the templates output,
displaying smarty version and date generated. Default is false.
$show_info_include
Shows an HTML comment before and after each included template.
Default is false.
$compiler_class
Specifies the name of the compiler class that Smarty will use
to compile the templates. The default is 'Smarty_Compiler'. For
advanced users only.
$request_vars_order
The order in which request variables are registered, similar to
variables_order in php.ini
$compile_id
Persistant compile identifier. As an alternative to passing the same
compile_id to each and every function call, you can set this compile_id
and it will be used implicitly thereafter.
$use_sub_dirs
Set this to false if your PHP environment does not allow the creation of
sub directories by Smarty. Sub directories are more efficient, so use them
if you can.
Methodsappendvoid appendmixed varvoid appendstring varnamemixed var
This is used to append data to variables in the template. You
can explicitly pass name/value pairs, or associative arrays
containing the name/value pairs.
append
// passing name/value pairs
$smarty->append("Name","Fred");
$smarty->append("Address",$address);
// passing an associative array
$smarty->append(array("city" => "Lincoln","state" => "Nebraska"));assignvoid assignmixed varvoid assignstring varnamemixed var
This is used to assign values to the templates. You can
explicitly pass name/value pairs, or associative arrays
containing the name/value pairs.
assign
// passing name/value pairs
$smarty->assign("Name","Fred");
$smarty->assign("Address",$address);
// passing an associative array
$smarty->assign(array("city" => "Lincoln","state" => "Nebraska"));clear_all_assignvoid clear_all_assign
This clears the values of all assigned variables.
clear_all_assign
// clear all assigned variables
$smarty->clear_all_assign();clear_all_cachevoid clear_all_cache
This clears the entire template cache. This was added to Smarty
1.3.0.
clear_all_cache
// clear the entire cache
$smarty->clear_all_cache();clear_assignvoid clear_assignstring var
This clears the value of an assigned variable. This
can be a single value, or an array of values. Array
functionality was added to Smarty 1.3.0.
clear_assign
// clear a single variable
$smarty->clear_assign("Name");
// clear multiple variables
$smarty->clear_assign(array("Name","Address","Zip"));clear_cachevoid clear_cachestring templatestring cache idstring compile id
This clears the cache for a specific template. If you have
multiple caches for this template, you can clear a specific
cache by supplying the cache id as the second parameter. You
can also pass a compile id as a third paramter. You can "group"
templates together so they can be removed as a group. See the
caching section for
more information.
clear_cache
// clear the cache for a template
$smarty->clear_cache("index.tpl");
// clear the cache for a particular cache id in an multiple-cache template
$smarty->clear_cache("index.tpl","CACHEID");clear_compiled_tplvoid clear_compiled_tplstring tpl_file
This clears the compiled version of the specified template
resource, or all compiled template files if one is not specified.
This function is for advanced use only, not normally needed.
clear_compiled_tpl
// clear a specific template resource
$smarty->clear_compiled_tpl("index.tpl");
// clear entire compile directory
$smarty->clear_compiled_tpl();displayvoid displaystring templatestring cache_idstring compile_id
This displays the template. Supply a valid template resource
type and path. As an optional second parameter, you can pass a
cache id. See the caching
section for more information.
As an optional third parameter, you can pass a compile id. This
is in the event that you want to compile different versions of
the same template, such as having separate templates compiled
for different languages. Another use for compile_id is when you
use more than one $template_dir but only one $compile_dir. Set
a separate compile_id for each $template_dir, otherwise
templates of the same name will overwrite each other. You can
also set the $compile_id variable once
instead of passing this to each call to display().
display
include("Smarty.class.php");
$smarty = new Smarty;
$smarty->caching = true;
// only do db calls if cache doesn't exist
if(!$smarty->is_cached("index.tpl"))
{
// dummy up some data
$address = "245 N 50th";
$db_data = array(
"City" => "Lincoln",
"State" => "Nebraska",
"Zip" = > "68502"
);
$smarty->assign("Name","Fred");
$smarty->assign("Address",$address);
$smarty->assign($db_data);
}
// display the output
$smarty->display("index.tpl");
Use the syntax for template resources to
display files outside of the $template_dir directory.
function display template resource examples
// absolute filepath
$smarty->display("/usr/local/include/templates/header.tpl");
// absolute filepath (same thing)
$smarty->display("file:/usr/local/include/templates/header.tpl");
// windows absolute filepath (MUST use "file:" prefix)
$smarty->display("file:C:/www/pub/templates/header.tpl");
// include from template resource named "db"
$smarty->display("db:header.tpl");fetchstring fetchstring templatestring cache_idstring compile_id
This returns the template output instead of displaying it.
Supply a valid template resource
type and path. As an optional second parameter, you can pass a
cache id. See the caching
section for more information.
As an optional third parameter, you can pass a compile id. This
is in the event that you want to compile different versions of
the same template, such as having separate templates compiled
for different languages. Another use for compile_id is when you
use more than one $template_dir but only one $compile_dir. Set
a separate compile_id for each $template_dir, otherwise
templates of the same name will overwrite each other. You can
also set the $compile_id variable once
instead of passing this to each call to fetch().
fetch
include("Smarty.class.php");
$smarty = new Smarty;
$smarty->caching = true;
// only do db calls if cache doesn't exist
if(!$smarty->is_cached("index.tpl"))
{
// dummy up some data
$address = "245 N 50th";
$db_data = array(
"City" => "Lincoln",
"State" => "Nebraska",
"Zip" = > "68502"
);
$smarty->assign("Name","Fred");
$smarty->assign("Address",$address);
$smarty->assign($db_data);
}
// capture the output
$output = $smarty->fetch("index.tpl");
// do something with $output here
echo $output;get_template_varsarray get_template_vars
This gets an array of the currently assigned template vars.
get_template_vars
// get all assigned template vars
$tpl_vars = $smarty->get_template_vars();
// take a look at them
var_dump($tpl_vars);is_cachedvoid is_cachedstring template[string cache_id]
This returns true if there is a valid cache for this template.
This only works if caching is set to true. This
was added to Smarty 1.3.0.
is_cached
$smarty->caching = true;
if(!$smarty->is_cached("index.tpl")) {
// do database calls, assign vars here
}
$smarty->display("index.tpl");
You can also pass a cache id as an an optional second parameter
in case you want multiple caches for the given template.
is_cached with multiple-cache template
$smarty->caching = true;
if(!$smarty->is_cached("index.tpl","FrontPage")) {
// do database calls, assign vars here
}
$smarty->display("index.tpl","FrontPage");load_filtervoid load_filterstring typestring name
This function can be used to load a filter plugin. The first
argument specifies the type of the filter to load and can be one
of the following: 'pre', 'post', or 'output'. The second argument
specifies the name of the filter plugin, for example, 'trim'.
loading filter plugins
$smarty->load('pre', 'trim'); // load prefilter named 'trim'
$smarty->load('pre', 'datefooter'); // load another prefilter named 'datefooter'
$smarty->load('output', 'compress'); // load output filter named 'compress'register_blockvoid register_blockstring namestring impl
Use this to dynamically register block functions plugins.
Pass in the block function name, followed by the PHP
function name that implements it.
register_block
/* PHP */
$smarty->register_block("translate", "do_translation");
function do_translation ($params, $content, &$smarty) {
if ($content) {
$lang = $params['lang'];
// do some translation with $content
echo $translation;
}
}
{* template *}
{translate lang="br"}
Hello, world!
{/translate}register_compiler_functionvoid register_compiler_functionstring namestring impl
Use this to dynamically register a compiler function plugin.
Pass in the compiler function name, followed by the PHP
function that implements it.
register_functionvoid register_functionstring namestring impl
Use this to dynamically register template function plugins.
Pass in the template function name, followed by the PHP
function name that implements it.
register_function
$smarty->register_function("date_now", "print_current_date");
function print_current_date ($params) {
extract($params);
if(empty($format))
$format="%b %e, %Y";
echo strftime($format,time());
}
// now you can use this in Smarty to print the current date: {date_now}
// or, {date_now format="%Y/%m/%d"} to format it.register_modifiervoid register_modifierstring namestring impl
Use this to dynamically register modifier plugin. Pass in the
template modifier name, followed by the PHP function that it
implements it.
register_modifier
// let's map PHP's stripslashes function to a Smarty modifier.
$smarty->register_modifier("sslash","stripslashes");
// now you can use {$var|sslash} to strip slashes from variablesregister_outputfiltervoid register_outputfilterstring function_name
Use this to dynamically register outputfilters to operate on
a template's output before it is displayed. See
template output
filters
for more information on how to set up an output filter function.
register_postfiltervoid register_postfilterstring function_name
Use this to dynamically register postfilters to run templates
through after they are compiled. See template postfilters for
more information on how to setup a postfiltering function.
register_prefiltervoid register_prefilterstring function_name
Use this to dynamically register prefilters to run templates
through before they are compiled. See template prefilters for
more information on how to setup a prefiltering function.
register_resourcevoid register_resourcestring namearray resource_funcs
Use this to dynamically register a resource plugin with Smarty.
Pass in the name of the resource and the array of PHP functions
implementing it. See
template resources
for more information on how to setup a function for fetching
templates.
register_resource
$smarty->register_resource("db", array("db_get_template",
"db_get_timestamp",
"db_get_secure",
"db_get_trusted"));trigger_errorvoid trigger_errorstring error_msg[int level]
This function can be used to output an error message using Smarty.
level parameter can be one of the values
used for trigger_error() PHP function, i.e. E_USER_NOTICE,
E_USER_WARNING, etc. By default it's E_USER_WARNING. This function
was added to Smarty 2.0.
template_existsbool template_existsstring template
This function checks whether the specified template exists. It can
accept either a path to the template on the filesystem or a
resource string specifying the template.
unregister_blockvoid unregister_blockstring name
Use this to dynamically unregister block function plugin.
Pass in the block function name.
unregister_compiler_functionvoid unregister_compiler_functionstring name
Use this to dynamically unregister a compiler function. Pass in
the name of the compiler function.
unregister_functionvoid unregister_functionstring name
Use this to dynamically unregister template function plugin.
Pass in the template function name.
unregister_function
// we don't want template designers to have access to system files
$smarty->unregister_function("fetch");unregister_modifiervoid unregister_modifierstring name
Use this to dynamically unregister modifier plugin. Pass in the
template modifier name.
unregister_modifier
// we don't want template designers to strip tags from elements
$smarty->unregister_modifier("strip_tags");unregister_outputfiltervoid unregister_outputfilterstring function_name
Use this to dynamically unregister an output filter.
unregister_postfiltervoid unregister_postfilterstring function_name
Use this to dynamically unregister a postfilter.
unregister_prefiltervoid unregister_prefilterstring function_name
Use this to dynamically unregister a prefilter.
unregister_resourcevoid unregister_resourcestring name
Use this to dynamically unregister a resource plugin. Pass in the
name of the resource.
unregister_resource
$smarty->unregister_resource("db");Advanced FeaturesPrefilters
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
registered or loaded from
the plugins directory by using
load_filter() function or by
setting
$autoload_filters variable.
Smarty will pass the template source code as the first argument, and
expect the function to return the resulting template source code.
using a template prefilter
<?php
// put this in your application
function remove_dw_comments($tpl_source, &$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 -->Postfilters
Template postfilters are PHP functions that your templates are ran through
after they are compiled. Postfilters can be either
registered or loaded
from the plugins directory by using
load_filter() function or by
setting
$autoload_filters
variable. Smarty will pass the compiled template code as the first
argument, and expect the function to return the result of the
processing.
using a template postfilter
<?php
// put this in your application
function add_header_comment($tpl_source, &$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... *}Output Filters
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.
Output filters can be either
registered or loaded
from the plugins directory by using
load_filter() function or by
setting
$autoload_filters
variable. Smarty will pass the template output as the first argument,
and expect the function to return the result of the processing.
using a template outputfilter
<?php
// put this in your application
function protect_email($tpl_output, &$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
?>Cache Handler Function
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.
Create a function in your application that Smarty will use as a
cache handler. Set the name of it in the
$cache_handler_func
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).
example using MySQL as a cache source
<?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, &$smarty_obj, &$cache_content, $tpl_file=null, $cache_id=null, $compile_id=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;
}
?>Resources
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.
Templates from $template_dir
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.
using templates from $template_dir
// from PHP script
$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 *}Templates from any directory
Templates outside of the $template_dir require the file: template
resource type, followed by the absolute path and name of the
template.
using templates from any directory
// from PHP script
$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"}Windows Filepaths
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.
using templates from windows file paths
// from PHP script
$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"}Templates from other sources
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.
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.
using custom resources
// from PHP script
// 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");
{* using resource from within Smarty template *}
{include file="db:/extras/navigation.tpl"}Default template handler function
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.
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.";
$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';
?>Extending Smarty With Plugins
Version 2.0 introduced the plugin architecture that is used
for almost all the customizable functionality of Smarty. This includes:
functionsmodifiersblock functionscompiler functionsprefilterspostfiltersoutputfiltersresourcesinserts
With the exception of resources, backwards compatibility with the old
way of registering handler functions via register_* API is preserved. If
you did not use the API but instead modified the class variables
$custom_funcs, $custom_mods, and
other ones directly, then you will need to adjust your scripts to either
use the API or convert your custom functionality into plugins.
How Plugins Work
Plugins are always loaded on demand. Only the specific modifiers,
functions, resources, etc invoked in the templates scripts will be
loaded. Moreover, each plugin is loaded only once, even if you have
several different instances of Smarty running within the same request.
Pre/postfilters and output filters are a bit of a special case. Since
they are not mentioned in the templates, they must be registered or
loaded explicitly via API functions before the template is processed.
The order in which multiple filters of the same type are executed
depends on the order in which they are registered or loaded.
There is only one plugins directory (for performance reasons). To
install a plugin, simply place it in the directory and Smarty will use
it automatically.
Naming Conventions
Plugin files and functions must follow a very specific naming
convention in order to be located by Smarty.
The plugin files must be named as follows:
type.name.php
Where type is one of these plugin types:
functionmodifierblockcompilerprefilterpostfilteroutputfilterresourceinsert
And name should be a valid identifier (letters,
numbers, and underscores only).
Some examples: function.html_select_date.php,
resource.db.php,
modifier.spacify.php.
The plugin functions inside the plugin files must be named as follows:
smarty_type_name
The meanings of type and name are
the same as before.
Smarty will output appropriate error messages if the plugin file it
needs is not found, or if the file or the plugin function are named
improperly.
Writing Plugins
Plugins can be either loaded by Smarty automatically from the
filesystem or they can be registered at runtime via one of the
register_* API functions. They can also be unregistered by using
unregister_* API functions.
For the plugins that are registered at runtime, the name of the plugin
function(s) does not have to follow the naming convention.
If a plugin depends on some functionality provided by another plugin
(as is the case with some plugins bundled with Smarty), then the proper
way to load the needed plugin is this:
require_once SMARTY_DIR . 'plugins/function.html_options.php';
As a general rule, Smarty object is always passed to the plugins as the last
parameter (except for modifiers).
Template Functionsvoid smarty_function_namearray $paramsobject &$smarty
All attributes passed to template functions from the template are
contained in the $params as an associative
array. Either access those values directly, e.g.
$params['start'] or use
extract($params) to import them into the symbol
table.
The output of the function will be substituted in place of the
function tag in the template (fetch function, for
example). Alternatively, the function can simply perform some other
task without any output (assign function).
If the function needs to assign some variables to the template or use
some other Smarty-provided functionality, it can use the supplied
$smarty object to do so.
See also:
register_function(),
unregister_function().
function plugin with output
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: function.eightball.php
* Type: function
* Name: eightball
* Purpose: outputs a random magic answer
* -------------------------------------------------------------
*/
function smarty_function_eightball($params, &$smarty)
{
$answers = array('Yes',
'No',
'No way',
'Outlook not so good',
'Ask again soon',
'Maybe in your reality');
$result = array_rand($answers);
echo $answers[$result];
}
?>
which can be used in the template as:
Question: Will we ever have time travel?
Answer: {eightball}.function plugin without output
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: function.assign.php
* Type: function
* Name: assign
* Purpose: assign a value to a template variable
* -------------------------------------------------------------
*/
function smarty_function_assign($params, &$smarty)
{
extract($params);
if (empty($var)) {
$smarty->trigger_error("assign: missing 'var' parameter");
return;
}
if (!in_array('value', array_keys($params))) {
$smarty->trigger_error("assign: missing 'value' parameter");
return;
}
$smarty->assign($var, $value);
}
?>Modifiers
Modifiers are little functions that are applied to a variable in the
template before it is displayed or used in some other context.
Modifiers can be chained together.
mixed smarty_modifier_namemixed $value[mixed $param1, ...]
The first parameter to the modifier plugin is the value on which
the modifier is supposed to operate. The rest of the parameters can be
optional, depending on what kind of operation is supposed to be
performed.
The modifier has to return the result of its processing.
See also
register_modifier(),
unregister_modifier().
simple modifier plugin
This plugin basically aliases one of the built-in PHP functions. It
does not have any additional parameters.
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: modifier.capitalize.php
* Type: modifier
* Name: capitalize
* Purpose: capitalize words in the string
* -------------------------------------------------------------
*/
function smarty_modifier_capitalize($string)
{
return ucwords($string);
}
?>more complex modifier plugin
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: modifier.truncate.php
* Type: modifier
* Name: truncate
* Purpose: Truncate a string to a certain length if necessary,
* optionally splitting in the middle of a word, and
* appending the $etc string.
* -------------------------------------------------------------
*/
function smarty_modifier_truncate($string, $length = 80, $etc = '...',
$break_words = false)
{
if ($length == 0)
return '';
if (strlen($string) > $length) {
$length -= strlen($etc);
$fragment = substr($string, 0, $length+1);
if ($break_words)
$fragment = substr($fragment, 0, -1);
else
$fragment = preg_replace('/\s+(\S+)?$/', '', $fragment);
return $fragment.$etc;
} else
return $string;
}
?>Block Functionsvoid smarty_function_namearray $paramsmixed $contentobject &$smarty
Block functions are functions of the form: {func} .. {/func}. In other
words, they enclose a template block and operate on the contents of
this block. Block functions take precedence over custom functions of
the same name, that is, you cannot have both custom function {func} and
block function {func} .. {/func}.
Your function implementation is called twice by Smarty:
once for the opening tag, and once for the closing tag.
Only the opening tag of the block function may have attributes. All
attributes passed to template functions from the template are contained
in the $params as an associative array. You can
either access those values directly, e.g.
$params['start'] or use
extract($params) to import them into the symbol
table. The opening tag attributes are also accessible to your function
when processing the closing tag.
The value of $content variable depends on
whether your function is called for the opening or closing tag. In case
of the opening tag, it will be null, and in case of
the closing tag it will be the contents of the template block.
Note that the template block will have already been processed by
Smarty, so all you will receive is the template output, not the
template source.
If you have nested block functions, it's possible to find out what the
parent block function is by accessing
$smarty->_tag_stack variable. Just do a var_dump()
on it and the structure should be apparent.
See also:
register_block(),
unregister_block().
block function
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: block.translate.php
* Type: block
* Name: translate
* Purpose: translate a block of text
* -------------------------------------------------------------
*/
function smarty_block_translate($params, $content, &$smarty)
{
if ($content) {
$lang = $params['lang'];
// do some intelligent translation thing here with $content
echo $translation;
}
}Compiler Functions
Compiler functions are called only during compilation of the template.
They are useful for injecting PHP code or time-sensitive static
content into the template. If there is both a compiler function and a
custom function registered under the same name, the compiler function
has precedence.
mixed smarty_compiler_namestring $tag_argobject &$smarty
The compiler function is passed two parameters: the tag argument
string - basically, everything from the function name until the ending
delimiter, and the Smarty object. It's supposed to return the PHP code
to be injected into the compiled template.
See also
register_compiler_function(),
unregister_compiler_function().
simple compiler function
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: compiler.tplheader.php
* Type: compiler
* Name: tplheader
* Purpose: Output header containing the source file name and
* the time it was compiled.
* -------------------------------------------------------------
*/
function smarty_compiler_tplheader($tag_arg, &$smarty)
{
return "\necho '" . $smarty->_current_file . " compiled at " . date('Y-m-d H:M'). "';";
}
?>
This function can be called from the template as:
{* this function gets executed at compile time only *}
{tplheader}
The resulting PHP code in the compiled template would be something like this:
<php
echo 'index.tpl compiled at 2002-02-20 20:02';
?>Prefilters/Postfilters
Prefilter and postfilter plugins are very similar in concept; where
they differ is in the execution -- more precisely the time of their
execution.
string smarty_prefilter_namestring $sourceobject &$smarty
Prefilters are used to process the source of the template immediately
before compilation. The first parameter to the prefilter function is
the template source, possibly modified by some other prefilters. The
plugin is supposed to return the modified source. Note that this
source is not saved anywhere, it is only used for compilation.
string smarty_postfilter_namestring $compiledobject &$smarty
Postfilters are used to process the compiled output of the template
(the PHP code) immediately after the compilation is done but before the
compiled template is saved to the filesystem. The first parameter to
the postfilter function is the compiled template code, possibly
modified by other postfilters. The plugin is supposed to return the
modified version of this code.
prefilter plugin
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: prefilter.pre01.php
* Type: prefilter
* Name: pre01
* Purpose: Convert html tags to be lowercase.
* -------------------------------------------------------------
*/
function smarty_prefilter_pre01($source, &$smarty)
{
return preg_replace('!<(\w+)[^>]+>!e', 'strtolower("$1")', $source);
}
?>postfilter plugin
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: postfilter.post01.php
* Type: postfilter
* Name: post01
* Purpose: Output code that lists all current template vars.
* -------------------------------------------------------------
*/
function smarty_postfilter_post01($compiled, &$smarty)
{
$compiled = "<pre>\n<?php print_r(\$this->get_template_vars()); ?>\n</pre>" . $compiled;
return $compiled;
}
?>Output Filters
Output filter plugins operate on a template's output, after the
template is loaded and executed, but before the output is displayed.
string smarty_outputfilter_namestring $template_outputobject &$smarty
The first parameter to the output filter function is the template
output that needs to be processed, and the second parameter is the
instance of Smarty invoking the plugin. The plugin is supposed to do
the processing and return the results.
output filter plugin
/*
* Smarty plugin
* -------------------------------------------------------------
* File: outputfilter.protect_email.php
* Type: outputfilter
* Name: protect_email
* Purpose: Converts @ sign in email addresses to %40 as
* a simple protection against spambots
* -------------------------------------------------------------
*/
function smarty_outputfilter_protect_email($output, &$smarty)
{
return preg_replace('!(\S+)@([a-zA-Z0-9\.\-]+\.([a-zA-Z]{2,3}|[0-9]{1,3}))!',
'$1%40$2', $output);
}
Resources
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.
There are a total of 4 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.
bool smarty_resource_name_sourcestring $rsrc_namestring &$sourceobject &$smartybool smarty_resource_name_timestampstring $rsrc_nameint &$timestampobject &$smartybool smarty_resource_name_securestring $rsrc_nameobject &$smartybool smarty_resource_name_trustedstring $rsrc_nameobject &$smarty
The first function is supposed to retrieve the resource. Its second
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.
The second function is supposed to retrieve the last modification time
of the requested resource (as a UNIX timestamp). The second 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, and false
otherwise.
The third function 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.
The fourth function 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 include_php tag or
insert tag with src
attribute. However, it should still be defined even for template
resources.
See also
register_resource(),
unregister_resource().
resource plugin
<?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
}
?>Inserts
Insert plugins are used to implement functions that are invoked by
insert
tags in the template.
string smarty_insert_namearray $paramsobject &$smarty
The first parameter to the function is an associative array of
attributes passed to the insert. Either access those values directly,
e.g. $params['start'] or use
extract($params) to import them into the symbol
table.
The insert function is supposed to return the result which will be
substituted in place of the insert tag in the
template.
insert plugin
<?php
/*
* Smarty plugin
* -------------------------------------------------------------
* File: insert.time.php
* Type: time
* Name: time
* Purpose: Inserts current date/time according to format
* -------------------------------------------------------------
*/
function smarty_insert_time($params, &$smarty)
{
if (empty($params['format'])) {
$smarty->trigger_error("insert time: missing 'format' parameter");
return;
}
$datetime = strftime($params['format']);
return $datetime;
}
?>