Difference between revisions of "Smarty Plugins"
TMMStephenY2 (talk | contribs) |
TMMStephenY (talk | contribs) m |
||
| Line 92: | Line 92: | ||
[[Category:Also NATS4 Article]] | [[Category:Also NATS4 Article]] | ||
| + | [[Category:NATS4 Skins and Templates]] | ||
Revision as of 14:18, 18 May 2011
NATS 3
|
|---|
Smarty Plugins 101
Although you cannot put PHP code directly into a Smarty template, you will be able to create Smarty Plugins written in PHP.
What is a Smarty Plugin?
The term "Smarty Plugin" refers to PHP code inside a single PHP function. Both the 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 use the format exemplified in the following code. Simply replace "xxx" in the example with a name of your choosing:
function smarty_function_xxx($params, &$smarty) {
}
Example
For example, if you wish to create a function that displays news items from a custom news system that is not included with, or available to NATS, name the function smarty_function_news or smarty_function_mynews. The list of parameters is standard, and should use the variables that have been listed above.
File Naming Convention
Your file name should always 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 under the NATS directly. This directory will usually be something along the lines of: nats/Smarty-(version)/libs/plugins. Keep in mind that if you have more than one Smarty-x.x.x (version) directory, the latest version of that directory is likely to be the correct version. If you are having difficulty locating your Smarty Plugins directory, please submit a support ticket, and we will identify your Smarty Plugins directory for you.
What can I do in this function?
You have the freedom to do whatever you wish with your custom Smarty plugins, as long as it does not alter any contents in the NATS database. Too Much Media company policy states that clients are not allowed to alter any contents in the NATS database.
Smarty Plugins are able to create direct output into the browser, return a variable or array with the output from your function, or do a combination of both tasks.
When you are on a template, you will be able to call the function by name. For example, you can input {mynews} to call your sample news function. You can also return data instead of outputting content directly to the browser. To do so, you must use the return xxx; keyword in your function-- simply replace xxx with the value you wish to return.
Examples
return $my_variable;
return "This request was processed correctly";
If your function does not return a value, the return statement will be unnecessary. In that case, 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 this example, the following variables and values would be available in the Smarty 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, will be available through the $params associative array. This is a simple and useful method, which allows you to give the function values based on what is currently available to the template, as well as allowing you to customize the function output based on those values.
Additional Notes on passing values into a Smarty Plugin Function
To make optional parameters for your function, check if it is using the isset() PHP function-- this will determine if the value is set prior to using it. If it is 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']
}
You may also find it useful to take all of the $params variables, 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";
}
