Revision as of 10:57, 17 December 2008
Smarty Plugins 101
You can't put PHP code directly into a Smarty template, but you can
create Smarty Plugins written in PHP.
What is a Smarty Plugin?
A Smarty Plugin is PHP code inside a single PHP function. Both file and
function name are named according to the Smarty Plugin standardized
naming conventions, which follows:
Function Naming Convention
The function name and parameters must use the following format. Replace xxx with
a name of your choosing:
function smarty_function_xxx($params, &$smarty) {
}
Example
To create a function that displays news from a custom news system not
included with or available to NATS, 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 should correspond with the function name. For example:
a function named smarty_function_mynews should be in the file function.mynews.php.
All Smarty Plugin PHP files must be placed in the
Smarty Plugins directory 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
can't find your Smarty Plugins directory, please
contact support and we will identify
your Smarty Plugins directory for you.
What can I do in this function?
You can do whatever you want with your custom Smarty plugins as long as
it doesn't alter the contents of the NATS database. It must not prevent
Too Much Media from being able to support your NATS installation.
A Smarty Plugin may create direct output into the browser, return a
variable or array with the output from the function, or do a
combination of both.
On a template, you can call the function by name. For example: {mynews}.
If you wan to return data instead of outputting content directly to the
browser, you must use the return xxx; keyword in the function.
Replace xxx with the value you want to return.
Examples
return $my_variable;
return "This request was processed correctly";
If your function does not return a value, you don't need to use
the return statement. We recommend that you return true or false for
all Smarty Plugins that send output to the browser.
Passing additional values or variables to the function
You can call a template function with extra parameters by including them
inside the Smarty braces. For example: {mynews count="5" daysback="7" category=$smarty.request.cat}.
In that case, 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
To make optional parameters, check for them using the isset() PHP
function to determine if the value is set prior to using it. If its
not set, you may use something else instead of that variable. For
example:
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 useful to take all of the $params variables and store
their values in local variables and assign values to those local
variables based on which $params variables are actually set.
For example:
if(isset($params['var_name'])) {
$local_var_name = $params['var_name'];
} else {
$local_var_name = "other value";
}
See Also
