Smarty Plugins 101
It is frequently asked - "how do put I PHP code in a Smarty template?" The
answer is technically - you cannot put PHP code into a Smarty template,
or at least you cannot put this code into the template directly. It's
possible to use a php_include to directly include a PHP script, but this
feature will soon be removed from NATS for security purposes. You will
still, however, be able to create and utilize Smarty Plugins.
What is a Smarty Plugin?
A Smarty Plugin is nothing more than PHP code encapsulated in a single
PHP function, in a single PHP file. Both file and function name are
named according to the Smarty Plugin standardized naming conventions;
which are as follows:
Function Naming Convention
The function name and parameters must be as follows, where xxx is an appropriate name of your choosing:
function smarty_function_xxx($params, &$smarty) {
}
Example
If you were creating a function that will display news from a custom
news system not included with or available to NATS, you might name the
function smarty_function_news or smarty_function_mynews. The
parameter list is standard and should use the variables listed above.
File Naming Convention
The file name must correspond with the function name. If the function
name is, for example, smarty_function_mynews, then the file must be
function.mynews.php. All Smarty Plugin PHP files must be placed in the
Smarty Plugins directory, which is found on your server in the NATS
directory, which is usually nats/Smarty-(version)/libs/plugins or
something similar to that. Keep in mind that if there is more than one
Smarty-x.x.x directory, the newest version of that directory is likely
the correct version. If you are unsure as to the location of your Smarty
Plugins directory, you may
contact support to ask us to identify your
Smarty Plugins directory for you.
What can I do in this function?
Technically, you can do whatever you would like to do, provided that it
doesn't alter the contents of the NATS database, as this may prevent Too
Much Media from being able to support your NATS installation.
Each Smarty Plugin may create direct output into the browser, return a
variable or array with the intended output from the function, or do a combination of both. The function will be called in the template by
name, such as {mynews} from the previous example; this all that is
required to execute the code that you've created in your custom Smarty
Plugin. It should be noted that if you intend on returning data rather
than outputting content directly to the browser, you must use the
“return xxx;” keyword in the function, where xxx is the literal
value (which must be contained in quotes or double quotes, depending on
the content) or a variable.
Examples
return $my_variable;
return "This request was processed correctly";
If your function does not return a value, you are not required to use
the return statement. It is recommended that for all Smarty Plugins
that are only intended to send output to the browser, that you return
TRUE or FALSE (1 or 0), for error checking purposes on the Smarty
template itself.
Passing additional values or variables to the function
If the function "smarty_function_mynews" is executed in the template as {mynews}, that means that the function did not receive any additional variables. If, however, the function was called as {mynews count="5" daysback="7" category=$smarty.request.cat}, the following variables and values would be available in the Plugin code:
$params['count'] (set to 5)
$params['daysback'] (set to 7)
$params['category'] (set to the contents of the GET, POST or COOKIE value for "cat")
Any variables passed into a function call by name, as in the previous
example, are available through the $params associative array. This is a
simple and useful method by which you may give the function values based
on what's currently available to the template and customize the function
output based on those values.
Additional Notes on passing values into a Smarty Plugin Function
If you intend making some of the values accepted by the function
optional, you should check for there existence before attempting to use
them, otherwise you will produce an error. You can use the isset()
PHP function to determine if the value is set prior to using it and
if it’s not, you may use something else instead of that variable.
if(isset($params['var_name'])) {
//code using the $params['var_name'] variable
} else {
//code using something other than $params['var_name']
}
It may also be use for to take all of the $params variable and store
their values in local variables and assign values to those local
variables based on which $params variables are actually set. In each
case, you could use something similar to this example code:
if(isset($params['var_name'])) {
$local_var_name = $params['var_name'];
} else {
$local_var_name = "other value";
}
See Also
