Internal Users

University Links

The Template Definition Language

The $ operator
The $this operators
The $exec{} operator
The @ operator
- The @local_path operator
#if..#else..#endif
- #if..#else..#endif and lists
#local..#endlocal
#external..#endexternal
#foreachrow
- #foreachrow @tour
#include
#createInclude
#includeForeachrow
Special include files
- #head
#buttons
Escaping #, $ and @

The `$` operator

During the operation of a particular template wrapper, various pieces of information will be made available to a template. This information can be included in a template by using the $ operator, along with the name of that piece of information, as described in the documentation for that wrapper.

For example, in the default template for creating staff pages (called staff_home_page.template):

<H4>$position<H4> <IMG SRC="faces/$uid.gif" ALT="">

This creates an H4 heading with the position of a member of staff and includes an image of the person gleaned from the user ID. Note:

the names of information inserts, or "variables" are in bold in the example above
the wrapper in question uses the template to create a page for every user ID registered as a member of staff. Hence all the information inserts listed in the documentation for staff_home_page.template are keyed on user ID (in this case at least)

The appropriate information will then be inserted into the template at run-time in order to generate a page for each member of staff.

The `$this` operator

$this operators are pre-defined cases of the $ operator that contain information about the environment of a web page.

`$this_server`

Contains the URL of the server, i.e. the protocol, hostname and port number.
E.g. http://www.cs.ukc.ac.uk:1997.

`$this_url`

Contains the full URL of the page, i.e. the protocol, hostname and port number and the filename.
E.g. http://www.cs.ukc.ac.uk:1997/dept_info/documentation/index.local.

`$this_uid`

Contains the uid of the person that generated the page (e.g. atp).
Mainly used by bap, but also used by bp, bipi, etc.

The `$exec{}` operator

$exec{} can be used to include the output of a shell command in a page generated from a template. The shell command should be given inside the curly brackets after the exec operator. For example, including the line:

Last modified $exec{date} / atp

in a template will result in the date being inserted at the end of every page generated from that template.

The `@` operator

The @ operator is used to describe lists of information inserts. There are two cases where it is used:

the general case, where more than one row of information is returned from a database query (used in conjunction with the #foreachrow operator to format individual rows of returned data - see below)
special, pre-defined cases where environment information is held (such as @local_path and foreachrow @tour - see below).

`@local_path`

Its contents depend on whether the the page being produced is local or external. The following example should make the operation clearer:

<LI><A HREF="/people/staff/$login.@local_path">$forename $surname<A>

This line is taken from research_group.template, and creates a bullet pointed entry for all research group academics, containing a hyperlink to their home page. The text of the link is their forename and surname.

When the wrapper creates the local version of the page, it replaces @local_path with the correct path to the local web space (/local-only/ in the current setup). When creating the external version of the page, @local_path is replaced with a blank, so pointing at the external web space.

Hence @local_path is a pre-defined @ operator containing information about the environment.

`#if..#else..#endif`

Provides a simple conditional control structure. The #if part should be followed by a $ operator, to test whether that information insert exists for the current case. For example:

#if $badge <DT>Current location <DD><A HREF="/cgi-bin/local-only/badge?$uid">Get active badge details</A> #endif

From staff.template, these lines will check to see whether the information insert $badge is defined for the member of staff currently being processed.

If it is then a hyperlink is generated that passes the staff member's user ID to a CGI script that will retrieve the relevant active badge details. After all, not everyone has an active badge, so not everyone needs a hyperlink from their homepage to the active badge CGI script.

#if $badge <DT>Current location <DD><A HREF="/cgi-bin/local-only/badge?$uid">Get active badge details</A> #else I don't have an active badge #endif

The above example demonstrates a trivial use of the #else keyword. If the user doesn't have an active badge, their page will contain a message saying so.

`#if..#else..#end` and lists

You should note that the #if..#else..#endif control structure also works with lists of information inserts, but that you should use the singular reference to the name of the list (i.e. $ and not @. This is because if @foo is a list, then $foo is separate information insert indicating whether the associated list is empty of not.

Here is the entire segment for generating lists of academic staff for each research group, taken from research_group.template (notice that both @ and $ are used to dereference group_academics, depending on its context:

#if $group_academics <H2><IMG SRC="/images/redsq2.gif" WIDTH="15" HEIGHT="15" ALT="*"> Academic staff</H2> <UL> #foreachrow @group_academics <LI><A HREF="/@local_path/people/staff/$login.html">$forename $surname</A> #endforeachrow </UL> #endif

`#local..#endlocal`

Used to mark-up an area of HTML as being for the local version of the page only. The HTML marked-up will not appear in the external version of the page.

For example, staff members may not want their campus location to be globally visible, hence:

#local <DT>Room <DD>$location #endlocal

`#external..#endexternal`

Used to mark-up an area of HTML as being for the external version of the page only. The HTML marked-up will not appear in the local version of the page.

For example, it may be convenient for direct telephone lines to appear on external pages (but not on local pages), hence:

#external <DT>Telephone <DD>82$extension #endexternal

`#foreachrow`

Used to loop through a list of information inserts (i.e. multiple rows returned from a database query), processing each insert in a group (or row). E.g.:

#foreachrow @group_academics <LI><A HREF="/@local_path/people/staff/$login.html">$forename $surname</A> #endforeachrow

These lines from research_group.template cycle through the rows held in the list named @group_academics, printing the contents of each field.

The fields available to template authors are listed in the documentation for research_group.template, under @group_academics. They are $login, $forename and $surname, and on every cycle of the loop they will contain the login, forename and surname (respectively) of a member of the academic staff for the research group specified to the template wrapper.

Hence the end result of the above code is to generate an unordered list of academic staff in the research group, complete with a hyperlink to each member's homepage.

It is sometimes useful, with optional lists (such as @group_academics, which may be empty if a research group has no academic members) to check with with a #if..#else..#endif as described above.

This can be seen from the following code (which is the same as the example above):

#if $group_academics <H2><IMG SRC="/images/redsq2.gif" WIDTH="15" HEIGHT="15" ALT="*"> Academic staff</H2> <UL> #foreachrow @group_academics <LI><A HREF="/@local_path/people/staff/$login.html">$forename $surname</A> #endforeachrow </UL> #endif

Notice that the list is checked for before any text/HTML associated with it is generated. Hence, if the list is empty, this section of code creates nothing, as would be expected.

`#foreachrow @tour`

Used in conjunction with btp, #foreachrow @tour will cycle through each destination specified (to btp at the command line) in the tour framework.

It is a special case of the #foreachrow control. When a tour framework is passed to btp, it will put the details of the tour into @tour. It is normally used to create links to each tour destination from the "tour start page".

Information available on each destination in the tour is as follows:

$tour_name: The name of the tour, or rather the tour framework, as it is found in the tour frameworks directory (/web/cs/httpd/docs/tours/tour_frameworks).
$exit_url: The URL of the "tour start page". Clicking on the stop tour button will take the user to this page.
$page: The number of a tour page within the tour (starting from zero).
$title: The title of a tour page (taken from between the HTML <TITLE></TITLE> tags)..

The following is some example code from a "tour start page" template that can be passed to btp to create a list of hyperlinks to, and titles of, destinations in a tour.

#foreachrow @tour #local <DD><P><A HREF="/cgi-bin/tour.@local_path?$tour_name&$exit_url&$page">$title</A></P> #endlocal #external <DD><P><A HREF="/cgi-bin/tour?$tour_name&$exit_url&$page">$title</A></P> #endexternal #endforeachrow

Hence foreachrow @tour is a pre-defined @ operator containing information about the environment.

`#include`

To include a file, use #include followed by the pathname of the file you want to include, in double quotes. E.g.:

#include "/home/cur/atp/webpages/foo"

Note that:

The filename should be relative to the current directory or absolute.
If the file you specify is not found an attempt will be made to create an empty file at the location specified.
The quoted file will be included into the body of the template before before any other actions are carried out. This allows you to use control structures, etc. in the include file. E.g.:
<P>This is an include file, <CODE>foo</CODE>, which demonstrates use of control structures as well.</P> #local <P>This is top secret internal info</P> #endlocal <P>Piggy in the middle</P> #external <P>This is globally visible</P> #endexternal

`#createInclude`

Enables the filename for a #include "filename" to be generated dynamically (at runtime).

This means that a template does not have to specify the actual filename to be included . Instead, a build script does this for you. The build script must generate the filename of the file to be included, and store this filename in the global %data hash array as the includeFile value, eg. in the build script there must be a statement of the form

$data{includeFile} = "myfilename"

where myfilename is the generated filename. If this build script uses a template which contains the line

#createInclude "$includeFile"

then that filename is included as if the template had specified #include "myfilename"

Note that:

Can only be used in conjunction with a build script which generates the filename and stores it as the $data{includeFile} = "myfilename"
(Rbargp, Rbrp, Rbrpgp uses this feature to build a page from a content file which is defined on the command line of each utility.)
The filename should be relative to the current directory or absolute.
If the file you specify is not found an attempt will be made to create an empty file at the location specified.
The quoted file will be included into the body of the template before before any other actions are carried out. This allows you to use control structures, etc. in the include file.

`#includeForeachrow`

Enables a #include "filename" type feature to be used within a #foreachrow element. The specified file is #included for every iteration of the array used in the foreachrow construct. The specified file may be a constant (resulting in the same file being included each time) or contain variables from the foreachrow array (enabling a different file to be #included for each iteration of the foreachrow).

To includeForeachrow a file, use #includeForeachrow followed by the pathname of the file you want to include, in double quotes. E.g.:

#includeForeachrow "/home/cur/mlb/webpages/foo"

The template used to create the research group membership webpage uses a #includeForeachrow to include each member's interests file in turn. It uses the filename interests.$login, where $login is different for each iteration of the @group_researchers array.

#if $group_researchers #foreachrow @group_researchers <tr> <td><a href="people/staff/$login/index.@local_path">$forename $surname</a> </td> <td> #includeForeachrow "/web/cs/docs/research/groups/$group_directory/membership/interests.$login" </td> </tr> #endforeachrow #endif

Note that:

The #includeForeachrow must only be used within a #foreachrow element.
The filename should be relative to the current directory or absolute.
If the file you specify is not found an attempt will be made to create an empty file at the location specified.
The quoted file will be included into the body of the template before before any other actions are carried out. This allows you to use control structures, etc. in the include file. E.g.:

Special include files

These are special include files. Not only do they take paramaters (passed after the name of the control), but they form the basic structure of every web page. They take away the need to repeatedly create HTML files with correct use of the <HTML>, <HEAD> and <BODY> tags.

`#head`

Parameters

Title string, used for <TITLE>..</TITLE>

Parameters

URL of image to use as "sider"

Parameters

None

`#buttons`

Used to create the active buttons at the bottom of most web pages. To create the buttons, just list a selection of the following button types after the #buttons control:

Name	Target
Admissions	none
CS	`/welcome.@local_path`
Courses	`/teaching/index.@local_path`
Dept	`/welcome.@local_path`
Doc	`/dept_info/documentation/index.local`
People	`/people/index.@local_path`
Pgrad	none
Pubs	`/pubs/index.@local_path`
Research	`/research/index.@local_path`
Search	`/search/index.@local_path`
Staff	`/people/staff/index.@local_path`
UKC	`http://www.ukc.ac.uk`
Ugrad	none