Introduction

In TGPX template system is very powerful and allows you to create nearly any type of design for your TGP and other script generated 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 TGPX 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 TGPX 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, which are in turn 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. Unlike the majority of the template commands, template comments may span multiple lines, which means the beginning {* delimiter and ending *} delimiter are not required to 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} {$gallery.gallery_url} {$partner.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 TGP Page Templates, Script Page 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: {$gallery.description|htmlspecialchars} In the example above the PHP function htmlspecialchars is applied to the {$gallery.description} 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.


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, '.', ',') TGPX includes some builtin template modifiers, which are described below:

treplace_special - This will replace all non-alphanumeric characters in a string with the replacement value you specify
Example: {$gallery.category|treplace_special::'_'}
This will replace all non-alphanumeric characters with an underscore

tnumber_format - This works exactly like the PHP number_format function, but uses the decimal point and thousands separator you have configured in the software settings. There are no values to pass to this template modifier.
Example: {$gallery.clicks|tnumber_format}

tsprintf - This is a wrapper around the PHP sprintf function, which is used for formatting strings.
Example: {$gallery.thumbnails|tsprintf::'%02d'}
This will display the thumbnail count for a gallery as an integer padded with a 0 if it is in the range 1-9

tdate - This will display a unix timestamp value formatted into a date. You can optionally pass the date format you want to use, but if you do not this function will use the date format you have configured in the software settings
Example: {$gallery.date|tdate}

tdatetime - This will display a unix timestamp value formatted into a date and time. You can optionally pass the date format you want to use, but if you do not this function will use the date and time formats you have configured in the software settings
Example: {$gallery.date|tdatetime}

thilite - This will go through a string and wrap each occurance of a search term in a <span> section with the class value of hilite. This can only be used in the search-results.tpl template, and is useful to highlight the search term that the user entered in the search results.
Example: {$gallery.description|thilite}

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 TGP Page Templates, Script Page Templates and E-mail Templates sections of the manual where appropriate.

Stock Functions

The TGPX template system offers several stock functions that can be used in any of the software 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 gallery links in bold text only if they are partner submitted galleries you could 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 contained within the {if} and {/if} tags.

In the {if} and {elseif} tags 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}, {foreachdone} {foreach from=$array_variable var=$loop_variable counter=$counter_variable} Array item: {$loop_variable.item_name}<br /> {foreachelse} There are no items to display {/foreach} The {foreach} function allows you to loop over any array of values. For example, when displaying galleries on your TGP pages you would use this function to display each gallery 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 available 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.

You can break out of a {foreach} section early by using the {foreachdone} template function. When this is encountered, the {foreach} loop will immediately stop and will not continue processing the remainder of the items.


{insert} {foreach from=$from var=$var counter=$counter} {insert counter=$counter location=+5 max=15} This code will be displayed in the locations specified {/insert} {/foreach} The {insert} function can be used inside the {foreach} and {range} template functions to display HTML code at specific positions that you define. For example, when displaying galleries on your TGP pages you could use this function to insert the necessary HTML code to create a HTML table to display your gallery links as thumbnails in a 5x5 layout. Every {insert} tag must be paired with a closing {/insert} tag and both the opening and closing tags must be located inside a {foreach} or {range} section. The {insert} function has 3 avialable attributes:


counter - This specifies the name of the counter value that was specified in the {foreach} or {range} function
location - This specifies the location(s) where you want the HTML code displayed (more on this below)
max - This specifies the maximum counter value after which no further inserts will be done.

There are three ways you can specify a location: a single insertion, multiple insertions, or multiple insertions at regular intervals. To specify a single insertion, enter the location as a number by itself. To specify multiple insertions, enter a comma separated list of locations. To specify multiple insertions at regular intervals, enter the interval with a + sign in front of it. The location numbers you use are related to the counter value you are working with. Here are a few examples:


3,7,10 - This will insert the HTML code in the 3, 7, and 10 positions.
+5 - This will insert the HTML code every 5 positions.
25 - This will insert the HTML code only once at position 25

The max value can be used to stop the insertions after a specific position. For example, if you wanted to insert code every 5 positions but want it to stop after the 30th position you would set the location value to +5 and the max value to 30. This would still insert the HTML code at the 30th position, but not at the 35th, 40th, etc.


{capture} {capture var=$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 var 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 {$captured_code} elsewhere in your template to display the code contained in that section.


{date} {date value='+1 day' format='m-d-Y' var=$tomorrow} The {date} function allows you to either display or store a date/datetime value. If the var attribute is specified, the date value will be stored in that variable which can be used later in your template to display the stored value. If the var attribute is left out, the date will be displayed in the location where the {date} function appears in the template. The {date} function also accepts two other attributes:


value - This specifies the value to use to calculate the date that should be displayed/stored
format - This specifies the date and time format to use to display the date

The value setting allows you to offset the date so that you can display any date relative to today's current date. Some of the available offset values you can use are:


year - Offset by years
month - Offset by months
day - Offset by days
hour - Offset by hours
minute - Offset by minutes
second - Offset by seconds


Here are some examples of the settings you can use for the value attribute:


now - Today's date
today - Today's date
-1 day - Yesterday's date
-5 day - The date from 5 days ago
+2 day - The date 2 days from now
-1 week - The date 1 week ago
-1 week -2 day - The date 1 week and 2 days ago
2 days ago - The date 2 days ago



{locale} {locale value=nl_NL} The {locale} function allows you to set a specific locale to use for the {datelocale} function so that you can get weekday and month names in a specific language. The value attribute specifies the language that should be used for month and weekday names. The setting you will use for the value attribute will depend on your server, since this uses the server's locale information. On some servers you can enter a literal string name of the language, for example value=swedish to get date values in Swedish. Others require that you use the special locale codes such as nl_NL for Dutch. You can also view the documentation for the PHP setlocale() function which has more information on locale values.


{datelocale} {datelocale value='-1 day' format='%A' var=$yesterday} The {datelocale} function is identical to the {date} function except that it takes into account your locale that has been set with the {locale} function and that it uses different format values for the format attribute. The date and time format documentation covers the available format values you can use for the format setting of this function.


{literal} {literal} <script language="JavaScript"> function checkForm(form) { if( form.site_url == '' ) { alert('The site URL field must be filled in'); return false; } return true; } </script> {/literal} Use the {literal} function to prevent template parsing from occurring 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 within 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 occurence of that {assign} tag.