Difference between revisions of "Smarty Plugins"
From TMM Wiki
Jump to navigationJump to searchm |
TMMStephenY2 (talk | contribs) |
||
| Line 7: | Line 7: | ||
== Smarty Plugins 101 == | == 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. | |
| − | create Smarty Plugins written in PHP. | ||
== What is a Smarty Plugin? == | == 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 | + | function name are named according to the Smarty Plugin standardized naming conventions, which are as follows: |
| − | naming conventions, which follows: | ||
== Function Naming Convention == | == Function Naming Convention == | ||
| − | The function name and parameters must use the following | + | 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: |
| − | a name of your choosing: | ||
<pre> | <pre> | ||
| Line 26: | Line 23: | ||
=== Example === | === Example === | ||
| − | + | ||
| − | included with or available to NATS, name the function | + | 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. |
| − | ''smarty_function_news'' or ''smarty_function_mynews | ||
| − | list is standard and should use the variables listed above. | ||
== File Naming Convention == | == 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.'' | + | 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 [http://clients.toomuchmedia.com/ submit a support ticket], and we will identify your Smarty Plugins directory for you. |
| − | All Smarty Plugin PHP files must be placed in the | ||
| − | Smarty Plugins directory | ||
| − | ''nats/Smarty-(version)/libs/plugins'' | ||
| − | Keep in mind that if | ||
| − | |||
| − | |||
| − | [http://clients.toomuchmedia.com/ | ||
| − | your Smarty Plugins directory for you. | ||
== What can I do in this function? == | == What can I do in this function? == | ||
| − | You | + | 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. |
| − | it | ||
| − | Too Much Media | ||
| − | + | 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. | |
| − | variable or array with the output from | ||
| − | combination of both. | ||
| − | + | 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. | |
| − | |||
| − | browser, you must use the | ||
| − | |||
=== Examples === | === Examples === | ||
| Line 66: | Line 46: | ||
</pre> | </pre> | ||
| − | If your function does not return a value, | + | 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. |
| − | the return statement. | ||
| − | all Smarty Plugins that send output to the browser. | ||
== Passing additional values or variables to the function == | == Passing additional values or variables to the function == | ||
You can call a template function with extra parameters by including them | You can call a template function with extra parameters by including them | ||
| − | inside the Smarty braces. | + | inside the Smarty braces. |
| − | |||
| + | For example: <tt>{mynews count="5" daysback="7" category=$smarty.request.cat}</tt>. | ||
| + | |||
| + | In this example, the following variables and values would be available in the Smarty Plugin code: | ||
<pre> | <pre> | ||
$params['count'] (set to 5) | $params['count'] (set to 5) | ||
| Line 81: | Line 61: | ||
</pre> | </pre> | ||
| − | Any variables passed into a function call by name, as in the previous | + | 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. |
| − | example, | ||
| − | simple and useful method | ||
| − | on what | ||
| − | output based on those values. | ||
== Additional Notes on passing values into a Smarty Plugin Function == | == Additional Notes on passing values into a Smarty Plugin Function == | ||
| − | To make optional parameters, check | + | 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. |
| − | function | ||
| − | not set, you may use something else instead of that variable. | ||
| − | |||
| + | For example: | ||
<pre> | <pre> | ||
if(isset($params['var_name'])) { | if(isset($params['var_name'])) { | ||
| Line 101: | Line 75: | ||
</pre> | </pre> | ||
| − | + | 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. | |
| − | their values in local variables and assign values to those local | + | |
| − | variables based on which $params variables are actually set. | ||
For example: | For example: | ||
Revision as of 14:19, 29 July 2010
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";
}
