HTML Templates

Contents / New Features / Administrator Docs / Developer Docs / Index

This document has the following sections:

Overview of the Template Feature
Using the Templates Feature
Guidelines For Using Templates

Overview of the Template Feature

Purpose

The HTML Templates feature of the Java Web Server allows you to easily apply common elements ("look and feel") as well as common content to a set of HTML documents without actually changing the HTML files themselves. All of these common items are contained in a single file -- called the template file.

Advantages

The obvious advantage of using the HTML Templates feature is that you can establish, and later update, the way multiple files appear all from one template file. This is especially helpful in cases where content is created before the presentation is decided or when content from multiple origins must be combined into some cohesive presentation. Rather than go back and edit all those files, you simply create a template file which uniformly applies the desired presentation elements.

Besides the application of headers and footers to your HTML files, you can also define body content to appear before or after the content of the source HTML documents. This can be a simple but powerful way of including information such as common product introductions, late-breaking news, or product cautions/caveats.

For instance, Joe's Widget web site could have every page announce

"Late-breaking news: Joe's Widget has just been named Widget of the Year. For more information on the award, see www.widgetawards.com"

A software vendor could include the following introductory text for pages describing a pre-release product:

"This document describes pre-release software provided as-is and without warranty of any sort. Features are subject to change without notice."

When the news becomes old (in the first case) or the product is released in final version (in the second case) the template can be updated to remove or replace this text.

What You Do

Using a default.template file, you specify the appearance (look and feel) to be applied by the Java Web Server to each of a set of files you designate.

What the Java Web Server Does

When a browser requests a file from the Java Web Server that has been designated to have the common elements of the default.template applied, a special Java servlet (TemplateServlet) is called. The servlet uses the template information to process the file. The resulting file, now reflecting the specified appearance, is then passed to the browser. Note that the file being displayed is not actually changed on disk, only its appearance in the browser is changed.

Using the Template Feature

To use the Template feature, you need to:

Specify the Common Elements
Create a file with named default.template. This template file should be a well-formed HTML file containing: opening HTML tag, a HEAD section, a BODY section, and a closing HTML tag. Insert one or more presentation elements into the desired location in the template file -- just as you would insert these elements into any HTML file.
Some of the presentation elements you might want to apply to your files include:
- Document color scheme (for example, background color, text color, and link color)
- Document layout (for example, a table of navigation links)
- A common header at the start of each page (for example, the product name)
- A common piece of art work at the start of each page (for example, the company or product logo)
- A common footer at the end of each page (for example, email address and fax number)
The template file should also contain the following tags:
1. in the HEAD section, <subst data="HEAD"></subst>
  This is an HTML extension that the TemplateServlet recognizes. It is a directive to the servlet to copy the contents of the source document's HEAD section into the HEAD section of the template file
2. in the BODY section, <subst data="BODY"></subst>
  This is another HTML extension that the TemplateServlet recognizes. It is a directive to the servlet to copy the source document's BODY into the BODY section of the template file. Because the directive only copies the contents of the source file's BODY section, and not the BODY tag itself, the template's own BODY tag can be set with the desired common attributes (background color, text color, etc.).
This template file, default.template, should be placed in the topmost directory containing HTML files to which you want the template applied.

Make sure the Java Web Server has loaded the Template Servlet
In the Administration Tool:
1. Select Web Service and click Manage
2. Click the Servlets button
3. Under Configure, scroll down to template
4. Click on template
A tabbed notebook will be shown. The Configuration page of the notebook tells you the full class name of the template. There are also Load at Startup and Loaded Now entries on the page, these should both indicate Yes. If they do not, then set them to Yes by pressing the Yes radio button.

Indicate the Files to which the Template should be Applied
Specifying the files to which the template should be applied involves using the Servlet Alias feature of the Java Web Server's Administration Tool. Brief instructions are provided below. For more information on mapping files or directories to servlet aliases, see Servlet Alias.

To map a set of files to a servlet alias, in the Administration Tool:
1. Select Web Service and click Manage
2. Click the Setup button
3. Click Servlet Aliases
4. In the Alias column, enter the /template directory or a filename pattern (such as *html) to which the alias will apply.
5. In the Servlet Invoked column, type template. This will map the directory to the servlet alias template.
Note: When you specify the /template directory, it is actually the <server_root>/public_html/template directory. This is because the directory in the Alias column is always relative to the document base directory, <server_root>/public_html/.

For even greater flexibility, a definitions file can be used in conjunction with the template file:

The definitions file is a simple Java properties file. It contains a list of name/value pairs that are used by the template file.

Definition files apply to the directory in which they reside plus all subdirectories. If another definitions file exists in a subdirectory, it inherits the attributes of the parent file and can override, or redefine, selected attributes. Thus, storing variations of the definitions in subdirectories allows you to further customize the look of your files on a directory-by-directory basis.

As an example, suppose you define an element called "NAV". The string included in the BODY section of the template file would read:
<subst data="NAV"></subst>

The string contained in the parent definition file might read:
NAV=<P><UL><LI><Topic1></LI><LI>Topic2</LI> </UL></P>

The string contained in a subdirectory definition file might read:
NAV=<P><UL><LI><Topic1></LI><LI>Topic2</LI><LI><Topic3></LI></UL></P>

Files contained in the directories between the parent definition file and the subdirectory containing the second definition file will have 2 topic entries in their navigation panels. Files in the subdirectory containing the second definition file (and all files below that, or until another definition file is encountered), will have 3 topic entries in their navigation panels. Thus, definition files enable you to create a different look for your files on a directory-by-directory basis.

A Sample using the Template

Common Elements Specification for Sample

The Java Web Server provides a sample default.template file, which uses abbreviations defined in the default.definitions file. These sample files are in the server_root/public_html/template directory. (server_root/public_html/ is sometimes called the document base directory.)

File Specification for Sample

For the sample, select the files in the /template directory as the set of files that you want the common elements specification applied. To do this, in the Administration Tool:

Select Web Service and click Manage

Click Setup

Select Servlet Aliases

Scroll through the Alias column. You should see /template and, under the Servlet Invoked column, template.
If there is no entry for /template in the Alias column, select the last entry in the Alias field, click Add. This will create a new entry space into which you should type /template. Hit the tab key to move to the Servlet Invoked column and then type template.

Results from Sample

You can see the end results of using the sample template and the sample file specification by opening the template/index.html file in a browser served by the Java Web Server, and then following the indicated links.

Guidelines For Using Templates

Generic HTML Files
Any HTML files to which you apply the templates should be generic HTML files. That is, files in which there is no explicit "look and feel" (banners, beginning images, headers, footers) already present. This is because the template adds elements to those already present in the source files, but cannot replace or remove elements.
Take as an example a case in which some of the source files already had a banner. If the template contains a common banner, the servlet processing would result in those files contain TWO (source and template) banners, while the source files with no banner would exit processing with ONE (template) banner.
Of course, if every one of your source HTML files already has a banner, then you can simply make a default.template file that does not insert a banner.

Well-formed HTML Files
Be sure that your source HTML files (to which the template will be applied) are "well-formed". This means that the HTML is correctly formed with an opening <HTML> tag, a head section enclosed by <HEAD> </HEAD> tags, a body section enclosed by <BODY></BODY> tags, and a closing </HTML> tag. The template servlet's parser is very strict -- if you don't have proper markup, you may see pages with no content.

The default.template file
The default.template file goes in the document base directory. In general, there needs to be only one default.template file per document set. However, like the default.template files, more can be used in subdirectories to override attributes present in the parent default.template file.

The default.definitions file
A default.definitions file applies to the directory where it is located, and to all subdirectories unless another default.definitions file is encountered in a subdirectory.
If a subdirectory also contains a default.definitions file, and some element is defined in both files, the definition in the subdirectory file overrides the one in the directory above it.

Use of HTML Frames
The template file cannot read in a frameset from a source file because only the contents of the HEAD section and the BODY section are copied. However, there is nothing to stop you from using files processed by the template servlet as content in your own frameset.

Top

java-server-feedback@java.sun.com