Smarty-Methods

append

append --

void append ( mixed var)

void append ( string varname, mixed var [, bool merge])

This is used to append an element to an assigned array. If you append to a string value, it is converted to an array value and then appended to. You can explicitly pass name/value pairs, or associative arrays containing the name/value pairs. If you pass the optional third parameter of true, the value will be merged with the current array instead of appended.

Technical Note: The merge parameter respects array keys, so if you merge two numerically indexed arrays, they may overwrite each other or result in non-sequential keys. This is unlike the array_merge() function of PHP which wipes out numerical keys and renumbers them.

Example 13-1. append

// passing name/value pairs
$smarty->append("Name", "Fred");
$smarty->append("Address", $address);

// passing an associative array
$smarty->append(array("city" => "Lincoln", "state" => "Nebraska"));
?>

append_by_ref

append_by_ref --

void append_by_ref ( string varname, mixed var [, bool merge])

This is used to append values to the templates by reference. If you append a variable by reference then change its value, the appended value sees the change as well. For objects, append_by_ref() also avoids an in-memory copy of the appended object. See the PHP manual on variable referencing for an in-depth explanation. If you pass the optional third parameter of true, the value will be merged with the current array instead of appended.

Technical Note: The merge parameter respects array keys, so if you merge two numerically indexed arrays, they may overwrite each other or result in non-sequential keys. This is unlike the array_merge() function of PHP which wipes out numerical keys and renumbers them.

Example 13-1. append_by_ref

// appending name/value pairs
$smarty->append_by_ref("Name", $myname);
$smarty->append_by_ref("Address", $address);
?>

assign

assign --

void assign ( mixed var)

void assign ( string varname, mixed 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.

Example 13-1. assign

// passing name/value pairs
$smarty->assign(\\'Name\\', \\'Fred\\');
$smarty->assign(\\'Address\\', $address);

// passing an associative array
$smarty->assign(array("city" => "Lincoln", "state" => "Nebraska"));
?>

assign_by_ref

assign_by_ref --

void assign_by_ref ( string varname, mixed var)

This is used to assign values to the templates by reference instead of making a copy. See the PHP manual on variable referencing for an explanation.

Technical Note: This is used to assign values to the templates by reference. If you assign a variable by reference then change its value, the assigned value sees the change as well. For objects, assign_by_ref() also avoids an in-memory copy of the assigned object. See the PHP manual on variable referencing for an in-depth explanation.

Example 13-1. assign_by_ref

php
// passing name/value pairs
$smarty->assign_by_ref(\\'Name\\', $myname);
$smarty->assign_by_ref(\\'Address\\', $address);
?>

clear_all_assign

clear_all_assign --

void clear_all_assign ( void )

This clears the values of all assigned variables.

Example 13-1. clear_all_assign

// clear all assigned variables
$smarty->clear_all_assign();
?>

clear_all_cache

clear_all_cache --

void clear_all_cache ( [int expire_time])

This clears the entire template cache. As an optional parameter, you can supply a minimum age in seconds the cache files must be before they will get cleared.

Example 13-1. clear_all_cache

php
// clear the entire cache
$smarty->clear_all_cache();
?>

clear_assign

clear_assign --

void clear_assign ( mixed var)

This clears the value of an assigned variable. This can be a single value, or an array of values.

Example 13-1. clear_assign

// clear a single variable
$smarty->clear_assign("Name");

// clear multiple variables
$smarty->clear_assign(array("Name", "Address", "Zip"));
?>

clear_cache

clear_cache --

void clear_cache ( string template [, string cache_id [, string compile_id [, int expire_time]]])

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 parameter. You can "group" templates together so they can be removed as a group. See the caching section for more information. As an optional fourth parameter, you can supply a minimum age in seconds the cache file must be before it will get cleared.

Example 13-1. 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_tpl

clear_compiled_tpl --

void clear_compiled_tpl ( [string tpl_file [, string compile_id [, int exp_time]]])

This clears the compiled version of the specified template resource, or all compiled template files if one is not specified. if you pass a compile_id only the compiled template for this specific compile_id is cleared. if you pass an exp_time, then only compiled templates older than exp_time seconds are cleared, by default all compiled templates are cleared regardless of their age. This function is for advanced use only, not normally needed.

Example 13-1. clear_compiled_tpl

php
// clear a specific template resource
$smarty->clear_compiled_tpl("index.tpl");

// clear entire compile directory
$smarty->clear_compiled_tpl();
?>

clear_config

clear_config --

void clear_config ( [string var])

This clears all assigned config variables. If a variable name is supplied, only that variable is cleared.

Example 13-1. clear_config

// clear all assigned config variables.
$smarty->clear_config();

// clear one variable
$smarty->clear_config(\\'foobar\\');
?>

config_load

config_load --

void config_load ( string file [, string section])
This loads config file data and assigns it to the template. This works identical to the template config_load function.

Technical Note: As of Smarty 2.4.0, assigned template variables are kept across invocations of fetch() and display(). Config vars loaded from config_load() are always global scope. Config files are also compiled for faster execution, and respect the force_compile and compile_check settings.

Example 13-1. config_load

// load config variables and assign them
$smarty->config_load(\\'my.conf\\');

// load a section
$smarty->config_load(\\'my.conf\\', \\'foobar\\');
?>

display

display --

void display ( string template [, string cache_id [, string 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 this function.

Example 13-1. 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.

Example 13-2. 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");
?>

fetch

fetch --

string fetch ( string template [, string cache_id [, string 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.

Example 13-1. 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_config_vars

get_config_vars --

array get_config_vars ( [string varname])

This returns the given loaded config variable value. If no parameter is given, an array of all loaded config variables is returned.

Example 13-1. get_config_vars

php
// get loaded config template var \\'foo\\'
$foo = $smarty->get_config_vars(\\'foo\\');

// get all loaded config template vars
$config_vars = $smarty->get_config_vars();

// take a look at them
print_r($config_vars);
?>

get_registered_object

get_registered_object --

array get_registered_object ( string object_name)

This returns a reference to a registered object. This is useful from within a custom function when you need direct access to a registered object.

Example 13-1. get_registered_object

function smarty_block_foo($params, &$smarty)
{
if (isset($params[\\'object\\'])) {
// get reference to registered object
$obj_ref = &$smarty->get_registered_object($params[\\'object\\']);
// use $obj_ref is now a reference to the object
}
}
?>

get_template_vars

get_template_vars --

array get_template_vars ( [string varname])

This returns the given assigned variable value. If no parameter is given, an array of all assigned variables is returned.

Example 13-1. get_template_vars

php
// get assigned template var \\'foo\\'
$foo = $smarty->get_template_vars(\\'foo\\');

// get all assigned template vars
$tpl_vars = $smarty->get_template_vars();

// take a look at them
print_r($tpl_vars);
?>

is_cached

is_cached --

bool is_cached ( string template [, string cache_id [, string compile_id]])

This returns TRUE if there is a valid cache for this template. This only works if caching is set to true.

Example 13-1. 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 optional second parameter in case you want multiple caches for the given template.

You can supply a compile id as an optional third parameter. If you omit that parameter the persistent $compile_id is used.

If you do not want to pass a cache id but want to pass a compile id you have to pass null as cache id.

Example 13-2. 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");
?>

Technical Note: If is_cached returns true it actually loads the cached output and stores it internally. Any subsequent call to display() or fetch() will return this internally stored output and does not try to reload the cache file. This prevents a race condition that may occur when a second process clears the cache between the calls to is_cached and to display in the example above. This also means calls to clear_cache() and other changes of the cache-settings may have no effect after is_cached returned true.

load_filter

load_filter --

void load_filter ( string type, string 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\\'.

Example 13-1. loading filter plugins

$smarty->load_filter(\\'pre\\', \\'trim\\'); // load prefilter named \\'trim\\'
$smarty->load_filter(\\'pre\\', \\'datefooter\\'); // load another prefilter named \\'datefooter\\'
$smarty->load_filter(\\'output\\', \\'compress\\'); // load output filter named \\'compress\\'
?>

register_block

register_block --

void register_block ( string name, mixed impl, bool cacheable, mixed cache_attrs)

Use this to dynamically register block functions plugins. Pass in the block function name, followed by the PHP function callback that implements it.

The php-function callback impl can be either (a) a string containing the function name or (b) an array of the form array(&$object, $method) with &$object being a reference to an object and $method being a string containing the mehod-name or (c) an array of the form array(&$class, $method) with $class being a classname and $method being a class method of that class.

cacheable and cache_attrs can be omitted in most cases. See Controlling Cacheability of Plugins\\' Output on how to use them properly.

Example 13-1. register_block

$smarty->register_block("translate", "do_translation");

function do_translation ($params, $content, &$smarty, &$repeat)
{
if (isset($content)) {
$lang = $params[\\'lang\\'];
// do some translation with $content
return $translation;
}
}
?>

where the template is:

{* template *}
{translate lang="br"}
Hello, world!
{/translate}

register_compiler_function

register_compiler_function --

bool register_compiler_function ( string name, mixed impl, bool cacheable)

Use this to dynamically register a compiler function plugin. Pass in the compiler function name, followed by the PHP function that implements it.

register_function

register_function --

void register_function ( string name, mixed impl [, bool cacheable [, mixed cache_attrs]])

Use this to dynamically register template function plugins. Pass in the template function name, followed by the PHP function name that implements it.

cacheable and cache_attrs can be omitted in most cases. See Controlling Cacheability of Plugins\\' Output on how to use them properly.

Example 13-1. register_function

php
$smarty->register_function("date_now", "print_current_date");

function print_current_date($params)
{
if(empty($params[\\'format\\'])) {
$format = "%b %e, %Y";
} else {
$format = $params[\\'format\\'];
return 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_modifier

register_modifier --

void register_modifier ( string name, mixed impl)

Use this to dynamically register modifier plugin. Pass in the template modifier name, followed by the PHP function that it implements it.

Example 13-1. 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 variables
?>

register_object

register_object --

void register_object ( string object_name, object object, array allowed_methods_properties, boolean format, array block_methods)

This is to register an object for use in the templates. See the object section of the manual for examples.

register_outputfilter

register_outputfilter --

void register_outputfilter ( mixed function)

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.

The php-function callback function can be either (a) a string containing the function name or (b) an array of the form array(&$object, $method) with &$object being a reference to an object and $method being a string containing the mehod-name or (c) an array of the form array(&$class, $method) with $class being a classname and $method being a class method of that class.

register_postfilter

register_postfilter --

void register_postfilter ( mixed function)

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_prefilter

register_prefilter --

void register_prefilter ( mixed function)

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_resource

register_resource --

void register_resource ( string name, array 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.

Technical Note: A resource name must be at least two characters in length. One character resource names will be ignored and used as part of the file path, such as $smarty->display(\\'c:/path/to/index.tpl\\');

The php-function-array resource_funcs must have 4 or 5 elements. With 4 elements the elements are the functions-callbacks for the respective "source", "timestamp", "secure" and "trusted" functions of the resource. With 5 elements the first element has to be an object reference or a class name of the object or class implementing the resource and the 4 following elements have to be the method names implementing "source", "timestamp", "secure" and "trusted".

Example 13-1. register_resource

$smarty->register_resource("db", array("db_get_template",
"db_get_timestamp",
"db_get_secure",
"db_get_trusted"));
?>

trigger_error

trigger_error --

void trigger_error ( string 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.

template_exists

template_exists --

bool template_exists ( string 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_block

unregister_block --

void unregister_block ( string name)

Use this to dynamically unregister block function plugin. Pass in the block function name.

unregister_compiler_function

unregister_compiler_function --

void unregister_compiler_function ( string name)

Use this to dynamically unregister a compiler function. Pass in the name of the compiler function.

unregister_function

unregister_function --

void unregister_function ( string name)

Use this to dynamically unregister template function plugin. Pass in the template function name.

Example 13-1. unregister_function

php
// we don\\'t want template designers to have access to system files

$smarty->unregister_function("fetch");
?>

unregister_modifier

unregister_modifier --

void unregister_modifier ( string name)

Use this to dynamically unregister modifier plugin. Pass in the template modifier name.

Example 13-1. unregister_modifier

// we don\\'t want template designers to strip tags from elements

$smarty->unregister_modifier("strip_tags");
?>

unregister_object

unregister_object --

void unregister_object ( string object_name)

Use this to unregister an object.

unregister_outputfilter

unregister_outputfilter --

void unregister_outputfilter ( string function_name)

Use this to dynamically unregister an output filter.

unregister_postfilter

unregister_postfilter --

void unregister_postfilter ( string function_name)

Use this to dynamically unregister a postfilter.

unregister_prefilter

unregister_prefilter --

void unregister_prefilter ( string function_name)

Use this to dynamically unregister a prefilter.

unregister_resource

unregister_resource --

void unregister_resource ( string name)

Use this to dynamically unregister a resource plugin. Pass in the name of the resource.

Example 13-1. unregister_resource $smarty->unregister_resource("db");
?>