Skip To Content

August 2007, J Maber

Bodington Templates

Most pages output by Bodington are based on templates. This short article explains how the templates work and shows how they can be modified. Note that the system for processing templates underwent a major development several years ago and so this article refers to 'old templates' and 'new templates'. The old template system continues to be supported because it wasn't thought necessary to convert all the templates to the new system. However, when templates have required serious edits it has usually been sensible to convert to the new type of template.

Template Files

Old template files are based on HTML but with the addition of one new type of tag - <building>. This tag has one compulsory attribute: the command attribute and may have other attributes depending on the value of the command attribute. The normal HTML content is simply output when the page based on the template is requested but the <building> tags are replaced with dynamic content by Bodington before the resulting page is sent to the user.

New template files are based on XHTML, not HTML, but with the addition of a number of extra types of tag. An XHTML file is an XML file which can be validated against the XHTML document type definition. The Bodington new template files can be validated against a document type definition which is based on the one for XHTML and which is included in the installed Bodington web application.

There are three flavours of XHTML called strict, transitional and frameset and from these are derived three flavours of new template. The file names of the DTDs are xhtmltemplate1-strict.dtd, xhtmltemplate1-transitional.dtd and xhtmltemplate1-frameset.dtd. They can be found inside the bodington.jar file in the folder org/bodington/servlet/template. The bodington.jar file is a type of zip file and is located at {bodington web application}/WEB-INF/lib/

Templates can be edited with a plain text editor or a specialised XML editor. The intention of using XML as the basis for the file format is so you get the advantage of using standard XML tools to check that the edited template is still well formed and valid. It also makes it much easier to write reliable and flexible Java code for processing it.

The new template format provides tags which give a high degree of control to the system administrator because they provide some features of a programming language and so sophisticated effects can be achieved without the need for recompiling the Java source code provided by Bodington.

New Template Structure and Content

The high level structure (XML declaration etc. omitted for clarity)of a template looks like this;

<template>

<preparation>

</preparation>

<html>

<head>

</head>

<body>

</body>

</html>

</template>

This structure allows the template designer to do some setting up in the preparation section before any HTML has been output.



Here are some other elements;

<declare type=”boolean” name=”test”/>

<declare type=”java.lang.String” name=”a”/>

The declare element is used in the preparation section to name a variable that will be used in the template. Note, that for strings the full class name “java.lang.String” must be used in the type attribute and the only other type currently supported is “boolean”. Several variables are automatically declared and these have a variety of types;

org.bodington.servlet.Request request;

org.bodington.servlet.Response response;

java.io.PrintWriter writer;

org.bodington.servlet.facilities.Facility facility;

Understanding what these variables are for would require quite a lengthy explanation. In essence the request object represents the user's page request, response represents the response that Bodington will make to the user, writer derives from response and is where HTML data is written to. The facility is an object that represents the functionality of a particular type of resource in Bodington and the actual class name used in the declaration varies depending on the type of resource being accessed via the template.



<assign name=”b”><variable name=”a”/></assign>

Here the value of one variable a is assigned to another b. Both variables must have been previously declared.

Another important structure that can go into the preparation section, in head or in body is presented in this example:

<call>

<target method=”loginInitCookie”>

<variable name=”facility”/>

</target>

<parameters>

<variable name=”request”/>

<variable name=”response”/>

</parameters>

</call>

This results in a call to the method named LoginInitCookie of the Java object named facility. The method has two parameters, the request and the response. In this particular case the facility looks at the request object to see if the user's browser sent a certain cookie and if necessary will send a new cookie back to the browser via the response object. A call construct can also be used within an assign construct which results in the returned value of the method being assigned into the named variable. Calls can also be nested so that the return value of one method is passed as a parameter to another.

The template may include decision making via the use of this construct;

<if>

<test>variable or call that evaluates to a boolean here</test>

<then>processing if test is true</then>

<else>processing if test is false</else>

</if>

The 'then' and 'else' sections can output HTML or can contain method calls, variable assignments etc. You can nest 'if' sections one inside another. If you want to output html from within a then or else section then use the <htmlfragment>xhtml tags here</htmlfragment> construct. Another more subtle way to output HTML is to call the print method of the writer object. This will allow you to use a method call which returns a String value and pass to a method call that outputs that value to the user.

How are templates processed?

When a new template or an edited template is accessed by a user the Bodington system first converts the XML tags into Java source code and then compiles that source code into a Java class. Subsequently, whenever the page is requested a special method in that Java class is executed. How that happens in detail is best learned by studying the Bodington source code but it is worth discussing the location of the various files here.

Bodington resources each have a URL which looks like the URL of a directory, i.e. it ends with a slash. Any URL whose 'file name' starts with 'bs_template_' will be processed using the template system. The first stage of this process is to determine which template file to use based on the URL. The 'directory' part of the URL is used to determine several items of information;

The template file is determined from these properties in the following way (braces are used to indicate the substitution of a variable into the path name of the file);

This process allows for an object oriented approach and means that the directory which contains the largest number of template files is {templates}/style_default/default/ Specific types of resource can add and override functionality and style defined there.

A slight variation occurs in the case of a URL that appears to be a directory – this will be processed as if the file name were bs_template_index.html.

When the template file has been found, then a corresponding file name for a Java source file is determined. These appear in subdirectories of {bodington web application directory}/WEB-INF/template_classes/working/. There can be three files per template;

A practical example – top.html

The following is a fragment from the top.html with some notes.



The div element is a straightforward XHTML element and its start and end tags will be output just as they appear. However, the content that appears within can be generated dynamically.

<div id="Link">

The div element contains a span element which is another ordinary XHTML element.

<span class="Text">

This following if section determines the content of the span element.

<if>

The first element inside the if element must be a test element and the content of the test element must be some kind of expression that equates to a boolean value which will be used in the test.

<test>

In this test is a single call to the method named 'isAuthenticated()' in the Java object request. The method call requires no parameters so the parameters section is empty.

<call>

<target method="isAuthenticated"><variable name="request"/></target>

<parameters></parameters>

</call>

</test>

A then section follow the test section. It will only be processed if the result of the test is true. In this example the then section applies if the user has authenticated in any way.

<then>

Another if construct is nested inside this then clause.

<if>

Once again the test makes a call to the request object but this time the test determines whether the authentication method was anonymous. Anonymous authentication is when the user has chosen to log in as a visitor. In this inner if construct there is an else section as well as a then section. The then section is processed if the user is an anonymous visitor and the else section is processed if some other (presumably stronger) form of authentication was applied to this user.

<test>

<call>

<target method="isAnonymous">

<variable name="request"/>

</target>

<parameters></parameters>



</call>

</test>

<then>

Anonymous users get a link to user options which is expressed here as plain old XHTML.

<a target ="_top" href="bs_template_useroptions.html" title="Options">Options</a>

</then>

<else>



Users who have authenticated by a non-anonymous method get some dynamic and some static content within this else section. First a call into facility which dynamically generates a notify switch. The HTML actually generated depends on data stored in the database. The whole of this call section is equivalent to the Java statement: facility.navigation( request, response, “notifyswitch” );



<call>

<target method="navigation">

<variable name="facility"/>

</target>



<parameters>

<variable name="request"/>

<variable name="response"/>

<literal type="String">notifyswitch</literal>

</parameters>

</call>

The dynamic content generated by the above call is now followed by some static HTML.

<a target ="_top" href="bs_template_useroptions.html" title="Options">Options</a>



</else>

</if>

</then>

</if>

</span>

</div>



Changes to the template that involve editing the static XHTML tags are easy to implement. Here are some guidelines.