Difference between revisions of "NATS4 Skins"
| (6 intermediate revisions by the same user not shown) | |||
| Line 43: | Line 43: | ||
=== An Introduction to Smarty === | === An Introduction to Smarty === | ||
| − | Smarty a hybrid of HTML and PHP. You'll find that the structure of | + | Smarty is a hybrid of HTML and PHP. You'll find that the structure of |
Smarty resembles HTML and the actual keywords used are similar to | Smarty resembles HTML and the actual keywords used are similar to | ||
that of PHP. | that of PHP. | ||
| Line 50: | Line 50: | ||
names with a dollar sign. For example: {$data.name}. Smarty encloses | names with a dollar sign. For example: {$data.name}. Smarty encloses | ||
comments in "{*" and "*}" characters. Note: comments do not get sent to | comments in "{*" and "*}" characters. Note: comments do not get sent to | ||
| − | the browser, so | + | the browser, so comments will always remain hidden. |
Smarty Templates sometimes conflict with JavaScript and CSS code because | Smarty Templates sometimes conflict with JavaScript and CSS code because | ||
| − | JavaScript and CSS code use curly braces | + | JavaScript and CSS code also use curly braces. To make them compatible, |
enclose your JavaScript and CSS code in between "{literal}" and | enclose your JavaScript and CSS code in between "{literal}" and | ||
"{/literal}". | "{/literal}". | ||
| Line 63: | Line 63: | ||
You can specify a single header and footer for multiple templates to | You can specify a single header and footer for multiple templates to | ||
simplify your design and quickly generate content for the various areas | simplify your design and quickly generate content for the various areas | ||
| − | of NATS | + | of NATS. |
You can create your own header and footer template combination, but | You can create your own header and footer template combination, but | ||
| Line 75: | Line 75: | ||
* Admin - admin_header and admin_footer | * Admin - admin_header and admin_footer | ||
| − | Note: | + | Note: If you break the administrator headers while editing them, you |
cannot get back into your administration section to fix the error. If | cannot get back into your administration section to fix the error. If | ||
this happens, append the following text to the URL you're trying to access: | this happens, append the following text to the URL you're trying to access: | ||
| Line 89: | Line 89: | ||
directive to a template, save the template, and load the resultant page. | directive to a template, save the template, and load the resultant page. | ||
| − | WARNING: using {debug} on a public template poses a security threats and | + | '''WARNING''': using {debug} on a public template poses a security threats and |
displays a pop-up that confuses affiliates and surfers. | displays a pop-up that confuses affiliates and surfers. | ||
| Line 144: | Line 144: | ||
=== Interacting with Templates === | === Interacting with Templates === | ||
| − | Each template in the Skins and Templates admin can be customized, | + | Each template in the Skins and Templates admin can be customized, but |
you don't need to edit every template since there may be templates | you don't need to edit every template since there may be templates | ||
| − | that produce features that you won't implement | + | that produce features that you won't implement. But for the templates |
| − | that you want to customize, the act of doing so is fairly simplistic | + | that you want to customize, the act of doing so is fairly simplistic: |
# The Template Information area displays the name of the template and the description field. The description field is optional and may be blank. | # The Template Information area displays the name of the template and the description field. The description field is optional and may be blank. | ||
Latest revision as of 13:18, 20 July 2011
Skins
Before customizing your first template, you should understand how NATS uses skins. Skins let you create sets of templates that control the look and feel of NATS.
Finding the Skins and Templates Admin
Most templates can be edited in the Skins and Templates Admin.
Using the Skins and Templates Interface
The Import and Export links on the Skins and Templates Admin let you export a skin to to a file; the import feature takes a previously exported file and imports it back into NATS. Flushing the Template Cache rebuilds all of the templates on your server; you should only click this if you're having problems.
The Default Skin section lets you choose the default skin for each type of user. The public areas of NATS use the default skin assigned to affiliates. Affiliates get assigned the default skin when they create an account; when you change the default skin, it doesn't change the skin used by existing affiliate accounts.
The list of skins lets you choose which skin to change. You can change the name of skins, duplicate them, edit their templates, or delete them.
Duplicating Skins
When you duplicate a skin, it remains tied to its original. Any changes you make to a template in the original skin change the duplicate unless you've made a change to the same template in the duplicated skin.
Templates
A template describes how to display a Web page or part of a page. Most templates are grouped together by either a skin or site. Templates can contain HTML, DHTML, JavaScript, or CSS elements combined with code from the Smarty Template Engine.
The Smarty Template Engine gives you PHP-like features without having to modify the NATS source code.
An Introduction to Smarty
Smarty is a hybrid of HTML and PHP. You'll find that the structure of Smarty resembles HTML and the actual keywords used are similar to that of PHP.
All Smarty code is contained in curly brackets: "{}". Smarty prefixes variable names with a dollar sign. For example: {$data.name}. Smarty encloses comments in "{*" and "*}" characters. Note: comments do not get sent to the browser, so comments will always remain hidden.
Smarty Templates sometimes conflict with JavaScript and CSS code because JavaScript and CSS code also use curly braces. To make them compatible, enclose your JavaScript and CSS code in between "{literal}" and "{/literal}".
Smarty lets you create logic structures to control the presence or processing of your content.
You can specify a single header and footer for multiple templates to simplify your design and quickly generate content for the various areas of NATS.
You can create your own header and footer template combination, but we recommend that you start with the existing Header and Footer that correspond to the area that you're editing. NATS has the following standard Header and Footer combinations in use in the public area, affiliates' area, and admin area:
- External - external_header and external_footer
- Affiliates - members_header and members_footer
- Admin - admin_header and admin_footer
Note: If you break the administrator headers while editing them, you cannot get back into your administration section to fix the error. If this happens, append the following text to the URL you're trying to access:
- ?_skin=0 -- if your URL doesn't have any question marks already
- &_skin=0 -- if your URL already has a question mark
Debugging Your Templates
Since Smarty templates are primarily HTML, most debugging is for HTML. We recommend debugging HTML in the Firefox Web browser with one of more of the following add-ons: Web Developer, DOM Inspector, Firebug, HTML Validator, and View Source Chart. To debug Smarty, add the "{debug}" directive to a template, save the template, and load the resultant page.
WARNING: using {debug} on a public template poses a security threats and displays a pop-up that confuses affiliates and surfers.
Where to Find Templates
Find templates in four separate areas of the NATS Admin:
- The Skins and Templates Admin (Public, affiliate, admin, and miscellaneous templates).
- The Sites Admin (Join form, cascade, site mail, and other miscellaneous templates).
- The Mailing Admin (Mailer specific templates for each mailer).
- The PayVia Configuration Admin (Contains PayVia dump format templates).
The Skins and Templates Admin
The Skins and Templates Admin contains templates for the NATS interface. Before you can browse and edit the list of Templates, you must create a skin.
- Go to the Skins and Templates Admin and click on the Copy (Green Plus) button next to the "Default" skin.
- Type a Name in the prompt, click "ok", and then enter a Description for this Skin. Leave all of the "Active For" check boxes checked.
- Click the "Save button" next to your new skin to commit your changes.
Template Groupings and Naming Conventions
The template list contains templates from the NATS interface's Public, Affiliate, and Administrative areas. The templates follow specific naming conventions that help you identify which area, feature, and "step" the template services.
The "step" is a specific portion of an interface. Some interfaces are divided into multiple portions with different visual and functional content. For example: the Affiliate Adtools feature of the NATS interface can use one or more of up to 12 different templates, depending on the operation a given Affiliate might perform or the type of Adtool being retrieved. The following list of templates is grouped by area, feature, and step:
External Templates
External Templates generate content for non-authenticated areas of the NATS interface. These templates start with the word, "external_".
The Affiliate Templates
The "Affiliate" Templates generate content for the authenticated, non-Administrative areas of the NATS interface. The affiliate templates all begin with the word, "affiliate_".
The Admin Templates
The Administrator Templates generate content for the authenticated, Administrative areas of the NATS interface. The administrator templates all begin with the word, "admin_".
You shouldn't need to modify these templates.
The "Other" Templates
The "Other" Templates are those that are used to various elements of the NATS interface. They include "function_" templates, "include_" templates, "mail_" templates, and "notify_" templates.
Interacting with Templates
Each template in the Skins and Templates admin can be customized, but you don't need to edit every template since there may be templates that produce features that you won't implement. But for the templates that you want to customize, the act of doing so is fairly simplistic:
- The Template Information area displays the name of the template and the description field. The description field is optional and may be blank.
- The Header drop down list allows you to specify which header template this template will use. Header and footer template usage is optional.
- The Template Body box contains the actual content of this template. As previously described, this code is a mixture of HTML, JavaScript, CSS, and Smarty tags. Each template has its own unique and independent use - Please see The Template List section of this document for specific template information.
- The Footer drop down list allows you to specify which footer template this template will use. Header and footer template usage is optional.
- After all changes to this template have been made, you must click the Save Template button or Save & Continue button to commit your changes. Save Template will save your changes and return you to the Template List. Save & Continue will save your changes and remain in the Edit Template interface.
To customize a template, find the appropriate template, flag that template as customized, edit & save the template content, and then test the template and NATS interface which uses the template. You can edit or duplicate a template. Duplicated template have the same name as the original with a numerical suffix.
The copy template feature is most useful when you make big changes. Start by making a "backup" copy of your template; if there's a problem, copy and paste the contents of the backup copy back into the original template to return to the last working copy. You may also use the Circular Blue Arrows button (Revert) to revert back to the original inherited copy, but that will remove all the changes you ever made to that template.
Mailer Templates
Each of the two mailing templates has access to the same Smarty variables and resources. Both member and affiliate mailings have access to Smarty Variables that exactly match the field names from the accounts, account_details, and members tables. For a list of variables, please see the following articles:
The PayVia Templates
The PayVia templates (also know as Payment Dump templates) control the output of the Payments Admin. You can edit the or create a new PayVia Dump format; for details, please see the Advanced PayVia Admin article.
The Sites Admin Templates
NATS uses the Site Admin Templates to display cascade, join, and "result" pages to surfers. Each tour has its own templates so that each tour can look different Edit the site template by clicking the Edit Templates icon next to the site on Sites Admin.
Base Site Templates vs. Site/Tour Specific Templates
Base Site Templates are similar to the Default Skin in the Skins & Templates Admin. Unlike the Default Skin, you may modify the templates in Base Site Templates -- but do so with extreme caution. Any changes to Base Site Templates are overwritten completely each time NATS gets upgraded. Site templates are inherited from the Base Site Templates unless they are customized for a given Site/Tour.
Template inheritance lets you modify the Base Site Templates, then make Site/Tour specific changes and have the Base Site Template contents act as an alternative "starting point" for whichever templates in the Base Site Templates have been modified. It should also be noted that once a template is modified, that template exists independently of the Base Site Templates and updates to NATS will not affect that template's contents. This means that rather than starting with the Base Site Template contents that NATS has provided, they may be modified to make all Site/Tour specific templates start with an alternative set of contents -- this can save a great deal of data entry time.
The Template List
There are more than 30 templates in the Site Templates list, but 10 of those template are code examples for various things that can be done on the Join forms. Most commonly, the only template you'll modify is the Join template.
Testing the Templates
It's easy to test the denial templates, but approval templates or any templates used in successful transactions can only be tested with a real transaction. Real transaction are real transactions because most billers that provide "test accounts" or "test cards" do not fully cascade or get reported back to NATS the way that real transactions get reported. It's easy to test normally accessible templates, such as any type of join form, password retrieval form, and the cascade template.
In some cases, you can take information from recently joined member accounts and simulate the output of an approval or denial template, such that a test transaction will not be required.
Conclusions and More Information
Advanced Templating Techniques
Many of the templates found in the Skins & Templates System have three separate components -- the Header template, the Footer template, and the Body template. The topic of "Header/Footer wrapping" was first discussed on Template Basics -- this is an expansion of that discussion.
Body contents can be fully contained, aligned and controlled by the wrapper div that's opened in the header and closed in footer. This lets you quickly design many different page bodies for a single set of header and footer templates and easily and quickly include the same code in a multiple pages that all use the same header and footer templates.
Advanced Templating Techniques - Dynamic Smarty Code
Smarty lets you make your pages totally dynamic using programing techniques.
Conditional and Logic Statements
The primary logic structure available to Smarty is the {if}{elseif}{else} structure that provides conditional processing and output. The syntax for these statements is very simple:
{if condition} use this code {elseif condition} use this other code {else} use this other other code {/if}
If the first condition is true, the code between the first set of tags is parsed. If that condition is not true, then it looks at the next condition, and it continues to do this until it hits an {else} condition or until it reaches the closing if tag, {/if}. For example, checking the value of a variables:
{if $variable == "value"} process this text / code {else} process this text / code {/if}
In this example, if $variable has a value of "value", then the code
between the opening {if} and {else} tags will be used. If $variable does
not have a value of "value", then the code between the {else} and {/if}
tags gets used. You can extend this logic to unlimited {elseif}
statements and can an if statement within other if statements to get
additional levels of control.
Looping Structures
The "section" loop is the most commonly used loop in NATS templates. Usually, {section} loops repetitively process the contents of an array and create output based on each element in the array. This can condense design into smaller blocks of code that will run until a condition is met or until you run out of array elements. This array must be assigned to Smarty by a PHP script or created using a series of cumbersome assignment statements. In the NATS templates, the PHP script that created the Smarty array will assign its elements.
Example:
{section name=loop_name loop=$array_name}
Output: {$array_name[loop_name].field}<br>
{/section}
In the above example, the loop name is called "loop_name" and it is the "$array_name" variable. Inside the loop, we refer to the array as $array_name and use "loop_name" as the index of that array. Each field in the array may be referenced by using the "." character followed by the field name. If this array has one field called "field" that contains five values -- one, two, three, four, and five -- when this code runs, it produces the following output:
Output: one Output: two Output: three Output: four Output: five
Assignment Statements
Assignment statements are very simple and only require two parameters -- the name of the variable to store and the value to store. The value may be a literal value, enclosed in quotes or the value stored in a variable by referencing the variable name enclosed in back ticks:
{assign var='variable' value=`$other_variable`}
In contrast, you can use the {capture} statement to capture the template output and store it in a variable:
{capture name=capture_variable}
{$url_variable}?get_variable1={$variable1}&get_variable2={$variable2}
{/capture}
Capture statements let you capture the output of complex code, including output generated by Smarty functions, variables, and any other types of dynamic code output. The above example is similar to code used in several NATS templates to capture adtool links.
Smarty Plug-ins
Smarty Plug-ins are the best way to extend Smarty's functionality using PHP. A Smarty Plug-in is a PHP script with a specific naming convention and a single block of code, also with a specific naming convention. The most commonly plug-in is a functions. These files should be placed in the Smarty-(version)/libs/plugins/ directory so that Smarty can use them.
File Naming Conventions
function.name.php -- this means that if the function were called "parse_xml", then the file would be called function.parse_xml.php
Function Naming Conventions and Declaration Format:
function smarty_function_name($params, &$smarty)
To use the function name in the File Naming Convention example above, declare the function as function smarty_function_parse_xml($params, &$smarty). Note that the parameters of this function are standard. Smarty takes all individually named parameters passed into the function and stores them as an array in the variable called $params and the Smarty object will be passed into the function by Smarty, which is always &$smarty in the function declaration.
Each function is a return variable, a return array, or an assignment.
- Returning Data that will be outputted to the browser
- return $variable; or return "literal output";
- Assigning Smarty Variables rather than returning data -
- $smarty->assign(variable_name,$output);
If the function returns a value, referencing the function anywhere in the template will simply replace the function call with the output of the function. If the function assigns its output to a variable, you need to reference the variable to generate output. When calling the function, enclosed the function name in braces. For example:
{function_name}
You can pass function parameters in the function call. For example:
{function_name type="value1" source="value2" action=$variable}
</pre?
Reference those parameters in the Smarty Function:
<pre>
$params['var_name']
Reference values previously assigned to Smarty:
$smarty->get_template_vars('var_name');
