Introduction
In LinkX template system is very powerful and allows you to create nearly any type of design for your link directory pages. The template system is also used in the
e-mail messages that the software sends, so you can control the content of those messages as well. This document will give you an overview of the basic template features
you will need to understand.
Basic Syntax
With the LinkX template system, all template tags are enclosed within the delimiters { and }. All content outside of delimiters is displayed as static content, or unchanged.
When the LinkX template parser encounters template tags, it attempts to interpret them, and displays the appropriate output in their place.
Comments
Template comments are surrounded by asterisks, and that is surrounded by the delimiter tags like so:
{* this is a comment *}
Template comments are NOT displayed in the final output of the template, unlike <!-- HTML comments --> these are useful for making internal notes in the templates which
no one will see in the generated output. Template comments cannot span multiple lines, the beginning {* delimiter and ending *} delimiter must be on the same line in the template
code.
Variables
Template variables start with the dollar sign ($) and can contain numbers, letters and underscores like so:
{$password}
{$link.site_url}
{$account.username}
When a template variable is encountered by the template parser, the entire
template tag (including delimiters) is replaced by the value of that variable. Each of the templates will have different variables that you can use within them, so be sure to
review the
Directory Templates and
E-mail Templates sections of the manual to find out what variables
are available in each template.
Variable Modifiers
In addition to simply displaying variables, you can also apply modifier functions to them. This is useful for formatting purposes, for example, when displaying a date you can
specify the format that the date should appear in. Variable modifiers follow the variable name and are separated from it by a | character like so:
{$link.title|htmlspecialchars}
In the example above the PHP function htmlspecialchars is applied to the {$link.title} variable before it is displayed in the template. You can use any of the built in PHP functions
as long as it takes the variable you specified as the first parameter.
For security reasons, all data provided by users should be passed through a formatting function before it is displayed. For the majority of the user data, it should be passed through the
htmlspecialchars function to prevent the possibility of them inserting malicious HTML or JavaScript code into the data they submit.
It is also possible to specify additional function arguments with the modifiers. Function arguments will come after the variable modifier and will be separated by :: delimiters. So, for example, if
you wanted to use the PHP function number_format() you would do that like so:
{$variable|number_format::2::'.'::','}
This would call the number_format PHP function with the arguments like this:
number_format($variable, 2, '.', ',')
Functions
Function tags appear much like variable tags, but do not start with a dollar sign. These template tags will contain a function name followed by optional function attributes like so:
{function attribute1='value1' attribute2='value2'}
Some functions are block functions which have both an opening and closing tag. All of the HTML code that is inside the opening and closing tags will be processed by these functions.
Block functions look like this:
{function attribute1='value1' attribute2='value2'}
Some HTML code
or other template values
{/function}
The template system provides some stock functions which are available in all templates, and some custom functions which are only available in specific templates. The
Stock Functions are described in this section of the manual. Custom functions will be listed in the
Directory Templates and
E-mail Templates sections of the manual where appropriate.
Stock Functions
The LinkX template system offers several stock functions that can be used in any of the directory or e-mail templates. These stock functions are described here.
{if}, {else}, {elseif}
{if $name == 'Fred'}
Your name is Fred
{else}
I don't know your name
{/if}
{if $name == 'Fred'}
Your name is Fred
{elseif $name == 'Sally'}
Your name is Sally
{else}
I don't know your name
{/if}
The {if} function allows you to conditionally include sections of a template in the output. For example, if you wanted to display a link's rating only if the link
has received more than 5 ratings you can use the {if} template function. The {if} template function works much like the if statement in programming languages, and also
offers the {else} and {elseif} functions. Every {if} tag must be paired with a closing {/if} tag. The {elseif} and {else} tags must be cointained within the {if} and
{/if} tags.
In the {if} and {elseif} tags you all PHP conditionals and functions are recognized, such as ||, or, &&, and, is_array(), etc. The conditionals and functions must be enclosed
in the { and } delimiters and there must be a space after the "if" function name.
{foreach}, {foreachelse}
{foreach from=$array_variable var=loop_variable counter=counter_variable}
Array item: {$loop_variable.item_name}
{foreachelse}
There are no items to display
{/foreach}
The {foreach} function allows you to loop over any array of values. For example, when displaying search results you would use this function to display each result using the
HTML code contained within the {foreach} block function, instead of having to write the same code over and over again. Every {foreach} tag must be paired with a closing {/foreach} tag.
The {foreach} function has 3 avialable attributes:
from - This specifies the template variable to loop over
var - This specifies the variable name to use within the {foreach} block to display the values contained in the array
counter - This specifies the variable name that will be incremented for each item in the array
The from and var attributes are required; the counter attribute is optional.
If you would like to display some alternate HTML code when the array value is empty, you can use the {foreachelse} function. It must be contained with the {foreach} and {/foreach} tags.
The HTML code that comes between the {foreachelse} and {/foreach} tags will be displayed when there are no values in the array specified in the from attribute.
{capture}
{capture name=captured_code}
This code will be captured for use later in the template
{/capture}
The {capture} function allows you to store the code contained in this block function so it can be used later in the template. The name attribute of this function specifies the name
of the variable that this HTML code will be stored in. Every {capture} tag must be paired with a closing {/capture} tag. All of the HTML code contained within the {capture} and {/capture}
tags will be stored in a variable. In the example above the variable name is captured_code, so you could use {$CAPTURES.captured_code} elsewhere in your template to display the code contained in
that section.
{nocache}
{nocache}
{/nocache}
The {nocache} function allows you to specify sections of the template that should not be cached. By default all of the directory templates are cached to reduce the load on the server, however
if you need to leave portions of the page dynamic you can use this function. Every {nocache} tag must be paired with a closing {/nocache} tag. All of the HTML code contained with the {nocache}
and {/nocache} tags will not be cached with the rest of the page. This is useful, for example, if you want to have some PHP code in your templates that updates the page everytime someone views
the page, rather than only when the page is re-cached.
{literal}
{literal}
{/literal}
Use the {literal} function to prevent template parsing from occuring within a section of template code. Every {literal} tag must be paired with a closing {/literal} tag. All of the HTML code
contained with the {literal} and {/literal} tags will not be parsed as template code. This is useful, for example, if you want to use some JavaScript code on your page but need the template parser
to ignore the { and } characters contained within that code.
{range}
{range start=$start_variable end=$end_variable counter=counter_variable}
{/range}
The {range} function is another looping function similar to the {foreach} function, however this function only loops over a range of numbers instead of over an array of values.
Every {range} tag must be paired with a closing {/range} tag. All of the HTML code contained with the {range} and {/range} tags will be output for each iteration of the loop.
The {range} function has 3 avialable attributes (all are required):
start - This specifies the starting point of the loop. It can be an assigned template variable or a literal number
end - This specifies ending point of the loop. It can be an assigned template variable or a literal number
counter - This specifies the variable name that will be incremented for each loop iteration
{php}
{php}
echo "This is some PHP code";
{/php}
Use the {php} function to include some PHP code in your template. Every {php} tag must be paired with a closing {/php} tag. All of the code contained with the {php} and {/php} tags will
be processed as PHP code that is within <?PHP and ?> tags.
{file}
{file filename="/full/path/to/file.html"}
Use the {file} function to include the complete contents of a file in the output of your template. The filename attribute should specify the full path and filename you want to read from.
The entire contents of that file will be read and placed in the output of your template in the location of the {file} template tag.
{include}
{include filename="global-header.tpl"}
Use the {include} function to include the complete contents of a global template (those with filenames that start with global-) in another template. The filename attribute
should specify the name of the global template that you want to include within your other template. The entire contents of that global template will be read and placed in
the output of your template in the location of the {include} template tag.
{cycle}
{cycle values="#FFFFFF,#777777"}
Use the {cycle} function to cycle between two values within a loop (such as the {foreach} or {range} loop functions). The values attribute specifies the two values to cycle between.
They should be enclosed in quotes and separated by a comma. This function is useful, for example, to display alternating row colors in a table.
{assign}
{assign var=$new_variable value="variable value"}
Use the {assign} function to assign a template value during the template parsing process. The var attribute specifies the name of the template variable that you want to set, and the
value attribute specifies the value you want to assign to the variable. Using the example above, you would be able to use {$new_variable} in your template to display the string "variable value" anywhere
in your template after the occurance of that {assign} tag.