Smarty Plugins
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
- Smarty Online Documentation
- Smarty Plugin chapter
