Educational ICT Virtualisation Specialist

Twitter LinkedIn E-mail
Precedence Technologies Ltd
Technology House, 36a Union Lane
Cambridge, CB4 1QB, United Kingdom
T: +44 (0)8456 446 800 / +44 (0)1223 359900
F: +44 (0)8456 446 899 / +44 (0)1223 359459
E: enquiries@precedence.co.uk
HomePage

Jump To: Support > KB > Template

TemplateEngine

TemplateEngine is used as the core of a number of Precedence software products such as FileSurfer and NetManager Intranet. It is also used for many of our custom developments.

TemplateEngine allows the look and feel of dynamic webpages to be separated from the software that generates the pages. This means that the user interface can be significantly altered without any specific programming skills beyond the HTML and CSS necessary for the design work.

Introduction

A template HTML file is loaded by the software and then processed before sending the output to the web-browser. Most of the HTML/text contained will be sent through without being touched, however some characters have special meaning. The software itself creates what is known as a context. This contains the dynamic parts of the website. The context and template are combined to form the output, i.e. the template is static, but the context differs from page to page. More importantly, the information that the context contains will differ between different software. Therefore, this page will not document the details of the context, merely how it will be used.

Basic substitution

Text surrounded by [[ and ]] will be used to look up an item from the context.

Let us assume the template contains:
<title>[[title]]</title>
and that the context specifies that title is My Web Page. This will output
<title>My Web Page</title>
to the browser.

Multi-dimensional arrays can be accessed by separating the subscripts with commas, e.g. [[person,name]] will be replaced by context['person']['name'].

Literal blocks

You can surround blocks which should not be processed further with {{@ and @}}. This will avoid errors due to unintentional matches such as [[sdf*sdf]]

Conditional substitution

The character pairs {{ and }} are used to separate out blocks of text. You may use two question marks to define a conditions when this block will be displayed.

The simplest is whether a name is set in the context: {{?unread?You have unread emails}}

If unread is unset or set to zero (or false), then this will output nothing. However if unread has a value, the string You have unread emails will be output.

{{}} sections can span multiple lines and line breaks within these will be maintained in the output:

{{?option?<tr>
<td>line</td>
</tr>
}}

Remember you can also include normal substitutions (and even other nested conditional blocks):

{{?error?<h1>Error: [[error]]</h1>}}

You can use ! to reverse the logic: {{?!unread?You have read all your email}}

If/Then/Else can be used by surrounding the Then and Else blocks with more {{ and }} characters. For example:

This option is currently {{?option?{{enabled}}{{disabled}}}}

Always remember to close off your [[ and {{ tags correctly.

More complicated conditionals

You can do numeric comparisons:

You have [[unread]] email{{?!unread==1?s}}
  • == equals
  • < less than
  • > greater than
  • <= less than or equal to
  • >= greater than or equal to

And text comparisons:

It's a {{?day=='weds'?Wednesday}}

(less than or greater than will refer to alphabetical order for text).

The special := comparison is used to test when a string contains a substring given as a string:

{{?name:='s'?Your name contains the letter S!}}

or given as a variable:

{{?name:=sub?Your name contains the letter '[[sub]]'!}}

Calling functions

PHP functions can be called by using the * character in your context lookups: [[func*name]] will be replaced by value of function func([[name]]). Functions can be nested, e.g. [[func1*func2*func3*name]] will be replaced by func1(func2(func3([[name]])))

Looping over an array

Sometimes the context contains lists of data within a single name. These are looped over by using the | operator. N.B. the input must be a multi-dimensional array. Each iteration will return the next element in the trunk of the array. Example code:

include("classes/templateEngine.class");

$context['item'] = array(
array('name'=>'Apple', 'type'=>'fruit'),
array('name'=>'Banana', 'type'=>'fruit'),
array('name'=>'Cheese', 'type'=>'dairy')
);

$template = '<html><body>I like to eat:
<ul>
{{|item|{{<li>Item [[item,name]] of type [[item,type]]</li>}}}}
</ul>
</body></html>';
echo templateEngine::singleton()->combine($template, $context);

Outputs:

I like to eat:

  • Item Apple of type fruit
  • Item Banana of type fruit
  • Item Cheese of type dairy

This is not designed to work with a single-dimension array, i.e. the following will NOT work:

include("classes/templateEngine.class");

$context['item'] = array('Apple', 'Banana','Cheese');

$template = '<html><body>I like to eat:
<ul>
{{|item|{{<li>Item [[item]]</li>}}}}
</ul>
</body></html>';
echo templateEngine::singleton()->combine($template, $context);

Looping over nested/multi-dimension arrays

The above can be extended to deal with nested or multi-dimensional arrays

include("classes/templateEngine.class");

$context['how'][0]['method'] = 'eat';
$context['how'][0]['item'] = array(
array('name' => 'Apple', 'type' => 'fruit'),
array('name' => 'Banana', 'type' => 'fruit'),
array('name' => 'Cheese', 'type' => 'dairy')
);

$context['how'][1]['method'] = 'drink';
$context['how'][1]['item'] = array(
array('name' => 'Apple juice', 'type' => 'fruit'),
array('name' => 'Beer', 'type' => 'alcohol'),
array('name' => 'Cherryade', 'type' => 'soda')
);

$template = '<html><body>
<ol>{{|how|{{<li>I like to [[how,method]]:</li>
<ul>
{{|how,item|{{<li>Item [[how,item,name]] of type [[how,item,type]]</li>}}}}
</ul>}}}}
</ol>
</body></html>';
echo templateEngine::singleton()->combine($template, $context);

Outputs:

  1. I like to eat:
    • Item Apple of type fruit
    • Item Banana of type fruit
    • Item Cheese of type dairy
  2. I like to drink:
    • Item Apple juice of type fruit
    • Item Beer of type alcohol
    • Item Cherryade of type soda

Looping over a subset of an array

The ^ operator allow you to use an array to select a subset of items from another array. So in the following example, the item array contains all possible items, but the filter array contains just the keys of the items we want to output (in the correct order). These are combined using item^filter.

include("classes/templateEngine.class");

$context['item']['apple'] = array('name'=>'Apple', 'type'=>'fruit');
$context['item']['banana'] = array('name'=>'Banana', 'type'=>'fruit');
$context['item']['cheese'] = array('name'=>'Cheese', 'type'=>'dairy');

$context['filter'] = array('cheese', 'apple');
$template = '<html><body>I like to eat:
<ul>
{{|item^filter|{{<li>Item [[item^filter,name]] of type [[item^filter,type]]</li>}}}}
</ul></body></html>';
echo templateEngine::singleton()->combine($template, $context);

This outputs:

I like to eat:

  • Item Cheese of type dairy
  • Item Apple of type fruit
© Copyright Precedence Technologies 1999-2017
Page last modified on March 07, 2017, at 05:15 PM by sborrill