HTML Templates

HTML Templates is a powerful feature of Help Producer that allows you to customize the topic pages of your help file by providing a template for all topic pages. HTML templates are very similar to Active Server Pages (ASP), which is a way to deliver dynamic contents on Microsoft's Internet Information Server. Unlike active server pages that create pages dynamically, HTML templates generate topic pages when the help document is exported to a help project. If you are already familiar with ASP, you will have little trouble learning HTML templates.

HTML templates are based on HTML and scripts. You should be familiar with HTML, and have some programming experience with a scripting language such as JScript or VBScript. Although this topic introduces some scripting and programming concepts, it is not intended to teach you a scripting language. So, if you are new to scripting, take advantage of the many books, classes, and Internet resources which can help you to master these languages. At the bottom of this topic, you will find links to reference documentation.

The HTML Template Model

A HTML template is a HTML text file with the extension .html that contains a combination of HTML tags, text, and scripts. You can use any HTML or text editor to create HTML template files. Preferably, you would use a HTML that has support for Active Server Pages (ASP), such as the Microsoft Script Editor, which is included with Microsoft Word. To activate Microsoft Script Editor in Microsoft Word, go to the menu Tools, point to Macro, and click Microsoft Script Editor.

HTML templates are designed to be language neutral. You can use any scripting language for which you have installed a COM compliant scripting engine. Windows comes with VBScript and JScript scripting engines installed. We recommend JScript, which is widely known as JavaScript. All examples throughout this topic are written in JScript.

The HTML template is loaded when you export a help document. For each topic page, Help Producer will process the scripts contained in the template that is used to generate the topic page. The template can be used with or without a theme. The processing of the template occurs immediately after Help Producer builds an internal document object model representation of the topic. If a theme is used, the theme may further process the topic.

Creating a HTML Template

A HTML template consists of HTML tags, tags, and script. A script is a series of instructions used to sequentially issue commands to Help Producer. In HTML template files, scripts are differentiated from text and HTML by delimiters. Similar to ASP, Help Producer uses the delimiters <% and %> to enclose script commands. The following example shows a simple HTML template that contains a script command:

<%@ LANGUAGE="JScript" CODEPAGE="1252" %>
<HTML>
   <HEAD>
      <TITLE><%= ActiveTopic.Title %></TITLE>
   </HEAD>
   <BODY>
      <% Response.WriteBody(); %>
   </BODY>
</HTML>

The expression ActiveTopic.Title returns the title of the current topic page. When Help Producer processes this page, it replaces <%= ActiveTopic.Title %> with the topic page's title. The statement Response.WriteBody(); instructs Help Producer to insert the topic's body text into the output stream. If you open the generated topic page in a text editor, you may get a HTML page like this:

<HTML>
   <HEAD>
      <TITLE>My first help file</TITLE>
   </HEAD>
   <BODY>
      <P>This is my first shot at mastering HTML templates...</P>
   </BODY>
</HTML>

Using a HTML template

If you specify a HTML template in a Help Producer project, it will be used to transform all topic pages in the help project.

Apply a HTML template

On the Help Producer toolbar, click Configure Help Project .
From the tree view, select the category Filter, and select the tab Template.
In the text box HTML template, specify the path or filename to the HTML template.

Using Directives

Help Producer supports three script directives:

Script commands: <% ... %>
Output directives: <%= ... %>
Processing directives: <%@ ... %>

The script directive <% ... %> is used to enclose script commands. Within the delimiters, you can include any command that is valid for the scripting language you are using.

The output directive <%= expression %> displays the value of an expression. This output directive is equivalent to using Response.Write to display information. For example, the output expression <%= city %> generates the word Hamburg (the current value of the variable) in the topic page.

The processing directive <%@ keyword %> gives Help Producer the information it needs to process a HTML template file. For example, the following directive sets VBScript as the scripting language for the page:

<%@ LANGUAGE="VBScript" %>

The processing directive must appear on the first line of a HTML template file. To add more than one directive to a page, the directive must be within the same delimiter. The processing directive has the following keywords:

The LANGUAGE keyword sets the scripting language for the HTML template file.
The CODEPAGE keyword sets the character encoding for the HTML template file.

You can include more than one keyword in a single directive. Keyword/value pairs must be separated by a space. Do not put spaces around the equal sign (=).

The following example sets both the scripting language and the code page:

<%@ LANGUAGE="JScript" CODEPAGE="1252" %>

Mixing HTML and Script Commands

You can include, within script delimiters, any statement, expression, procedure, or operator that is valid for your scripting language. A statement, in JScript and other scripting languages, is a syntactically complete unit that expresses one kind of action, declaration, or definition. The conditional If...Then...Else statement that appears below is a common JScript statement:

<%
   if (Project.Toc.Locate(ActiveTopic).IsNew)
      sTopicType = "This is a new topic.";
   else
      sTopicType = "This is an old topic.";
%>
<P><%= sTopicType %></P>

In the example above, depending on whether the topic was flagged as new, the script assigns either the value "This is a new topic!" or the value "This is an old topic!" to the string variable sTopicType. The <%= sTopicType %> statement is replaced with the current value of the variable.

You can include HTML text between the sections of a statement. For example, the following script, which mixes HTML within an If...Then...Else statement, produces the same result as the script in the previous example:

<% if (Project.Toc.Locate(ActiveTopic).IsNew) { %>
   <P>This is a new topic.</P>
<% } else { %>
   <P>This is an old topic.</P>
<% } %>

This way of mixing HTML and script commands is convenient for wrapping the If...Then...Else statement around several lines of HTML text.

Rather than interspersing HTML text with script commands, you can insert HTML text directly into the document with a script command. To insert HTML text directly, use the built‑in object Response. The following example produces the same result as the previous scripts:

<%
if (Project.Toc.Locate(ActiveTopic).IsNew) {
   Response.Write("<P>This is a new topic.</P>");
} else {
   Response.Write("<P>This is an old topic.</P>");
}
%>

Setting the Language for a Page

HTML templates make it possible to write scripts in a variety of scripting languages. You can use any scripting language for which the appropriate scripting engine is installed on your computer.

The primary scripting language is the language used to process commands inside the <% and %> delimiters. By default, the primary scripting language is JScript. To set the primary scripting language for a single page, add the <%@ LANGUAGE %> directive to the beginning of your HTML template file.

The syntax for this directive is:

<%@ LANGUAGE="ScriptingLanguage" %>

Where ScriptingLanguage is the scripting language that you want to set for that particular page.

Setting the Encoding for a Page

To specify the encoding of the HTML template, add the <%@ CODEPAGE %> directive to the beginning of your HTML template file. Note that this directive does not change the encoding of the generated topic page. To change the encoding of a topic page, specify the content type in the Meta tag of the topic page.

The syntax for this directive is:

<%@ CODEPAGE="CodePage" %>

Where CodePage is the encoding that you want to use for that particular page.

Including Comments

The // comment characters are supported in JScript. These characters should be used on each comment line.

<%
   // This line and the following one are comments.
   // The following function will insert the body text of the topic page.
   Response.WriteBody();
%>

You cannot include a comment in an output expression. For example, the first line that follows will work, but the second line will not, because it begins with <%=.

<% name = "Joe"; // This script will work. %>
<%= name // This script will fail. %>

Using the Response Object

In addition to the Help Producer Help Producer Object Model, the template processor exposes a Response object, which provides access to the output stream. You can use this object to write directly to the HTML content stream.

public function Write(obj);
public function WriteBody();

Use the function Write to write an object to the HTML content stream. Use the function WriteBody to write the topic's body content to the HTML content stream.

Reference Information

JScript Documentation (Microsoft Developer Network)

VBScript Documentation (Microsoft Developer Network)