Templates

Return to the web gadgets page

A template is a block of text that a web gadget uses to format its output. Normally a template will contain text and HTML code, as well as various placeholders that will be replaced with values at the time it is displayed.

For example, a template can be used to display an error page when a web gadget encounters a problem, or when a visitor is rejected due to an ACL file. Or a template can be used to format an e-mail message that gets sent out from a web gadget.

Here is a very simple template file that might be used to display an error message in a form processor gadget:

Error Your submission was rejected for the following reasons: {error} Please back up and try again.

Note that it looks pretty much like any HTML file might, except for the {errror} bit. Whenever a value enclosed in "curly braces" is encountered in a template it indicates a placeholder. In this example {error} would be replaced with the value stored in the 'error' variable at the time the template is used. As we'll see, curly braces are also used for several other things...

Also note that PHP code placed in templates will not work.

Comments

Sometimes it's handy to be able to put comments in a template file that are ignored by the gadget. These are especially useful when you need to make changes to a complex template months or years after it was last updated and you can't remember why you did something a certain way.

Comments can be added to a template file by enclosing them in in {* and *} tags. They can span multiple lines, and everything between these two tags will be ignored. For example:

{* This template is displayed after a successful form submission *} Thank you for your submission, someone will get back to you ASAP!

Variables

Each web gadget will have its own list of variables available that you can embed in a template. These might include configuration information for the gadget, form input values, server information, etc.

To embed a variable into a template you simply enclose the name of the variable in "curly braces". For example, if you wanted to display a variable named "firstname" then your template should have {firstname} wherever you want that value to appear.

Sometimes it is necessary to alter the value of a variable before displaying it. For example, you might want to convert a value to upper case, or display a date in a custom format, etc.

There are many different functions available to do a variety of things like this, and you can apply any number of them in any order to any variable before it is displayed. To apply a function to a variable, you specify the function name after the variable like this:

Hello {firstname uppercase}, welcome to my site!

In that example, the value of the 'firstname' variable would be converted to all upper case letters before being displayed.

Some functions take one or more parameters. For example, the "left" and "right" functions will display the left or right 'N' characters of a variable. To specify the number 'N', you add a colon and then the number to the function. For example, "left:10" would display the first 10 characters of the variable, while "right:3" would display the last three characters. If a function takes multiple parameters they should be separated with commas.

Multiple functions can be applied to a value by separating each function with a 'pipe' or 'bar' character. The functions are applied in the order that they are specified. For example, to convert "firstname" to all lower case, then display only the first 6 characters you would use {firstname lowercase|left:6}.

Function	Parameters	Decription
date	format	Converts the value to a date value, then outputs it according to the 'format' string using PHP's date() function.
htmlentities		Converts applicable characters to HTML entities using PHP's htmlentities() function.
htmlspecialchars		Converts special characters to HTML entities using PHP's htmlspecialchars() function.
indent	number,first	Indents each line of the value by 'number' spaces (8 by default). If 'first' is 'yes' then it will also indent the first line (default is 'no').
left	length	Outputs the first 'length' characters of the value.
length		Outputs the length of the value as a number.
lowercase		Converts the value to all lower case letters.
md5		Outputs the MD5 hash of the value.
mysqlescape		Escapes a value making it safe for use in a MySQL query using PHP's mysql_escape_string() function.
nl2br		Replaces any newline characters with ' '.
numberformat	precision	Outputs the value as a number with commas between every three digits, and rounded to 'precision' decimal places.
right	length	Outputs the last 'length' characters of the value.
sha1		Outputs the SHA1 hash of the value.
soundex		Outputs the 'soundex' code for the value.
striptags		Strips out any HTML tags in the value.
substr	start,length	Outputs 'length' characters of the value, starting with character number 'start'.
ucfirst		Converts the first character of the value to upper case.
ucwords		Converts the first character of each word in the value to upper case.
uppercase		Converts the value to all upper case letters.
urlencode		URL encodes a value, making it suitable for use in a link, using PHP's urlencode() function.
wordwrap	width,break,cut	Wordwraps the value to fit within 'width' characters (75 by default if not specified). 'break' is a string that is inserted between each line of the new value (a newline by default). If 'cut' is 'yes' then large words in the value will be broken in half to fit (default is 'no').

Conditionals

Templates can also contain conditionals, which cause parts of the template to be used or ignored depending on the value of a variable. For example, you might want additional buttons to appear if you are accessing a gadget as an administrator as opposed to a regular visitor.

Let's look at a sample template that includes a conditional:

Name: {name} {if adminmode = 1}IP: {ip} {/if} Email: {email}

This template might be used to display part of a guestbook entry, for example. This template would always display the name and email values, but would only display the IP address field if the variable 'adminmode' is currently set to 1.

You can test a variable using the following operators:

OP	Example	Description
none	{if adminmode}	Test if a variable true or false. Any value other than 0, 'false', 'f', 'no', 'n', 'off', and 'disabled' is considered to be true.
=	{if name = Mark}	Test if a variable is equal to a value, but ignore the case of the letters.
==	{if name == Mark}	Test if a variable is equal to a value, including the case of the letters.
!=	{if name != Mark}	Test if a variable is NOT equal to a value, but ignore the case of the letters.
!==	{if name !== Mark}	Test if a variable is NOT equal to a value, including the case of the letters.
<	{if age < 18}	Test if a variable is less than a value.
<=	{if age <= 18}	Test if a variable is less than or equal to a value.
>=	{if age >= 18}	Test if a variable is greater than or equal to a value.
>	{if age > 18}	Test if a variable is greater than a value.
$	{if browser $ MSIE}	Test if a variable contains a value (substring).
~	{if hostname ~ /shaw.ca$/i}	Test if a variable matches a regular expression.

If the result of a test is true, then everything between the {if ...} and corresponding {/if} tag is processed, otherwise it is ignored. You may have nested conditionals, and they may span any number of lines.

Each web gadget will have its own set of variables that you can test. For details please consult the documentation for each gadget.