More Advanced Procedures > Using HTML Templates

The HTML topic page templates are used to define the layout and behavior of topic pages in all HTML-based output formats (HTML Help, Webhelp, eBooks and Visual Studio Help / MS Help 2.0). By default there is just one template called Default which is assigned to new topics automatically. However, you can define as many different templates as you like.

You can assign a different template to any topic in the Topic Options tab behind the main editor window. Just select the template you want to use in the drop-down list in the HTML Page Template: field.

See Editing HTML templates for details on how to edit templates.

Template location

Configuration > HTML Page Templates

This tab is only available for the standard Default topic page template. All user-defined templates can only be edited in the HTML Source Code tab.

Background colors:

These settings set the background colors for your topic header and body. The colors will be shown in the Help & Manual editor.

Text above topic:

Everything you enter in this box is inserted at the top of every topic, before your topic text. Effectively, this adds a header to your topics (beneath the actual topic header containing the topic title). This text is only shown in your output, not in the Help & Manual editor.

You can enter HTML tags here to format the text, including references to images.

Topics with headers have <Top>, <Previous> and <Next> links:

This allows you to activate navigation links in your topic headers, either as simple text links or is a graphical icons. To insert an icon click in the Image File column, click on the Browse button and select the file.

Image files must be located in one of the folders listed in your Project Search Path settings in Configuration > Common Properties > Project Search Path.

Text below topic:

Everything you enter in this box is inserted at the bottom of every topic, after your topic text. Effectively, this adds a footer to your topics. This text is only shown in your output, not in the Help & Manual editor.

Here too, you can enter HTML tags here to format the text, including references to images.

This tab gives you full access to the HTML code of the template file. Editing HTML templates directly requires experience with editing HTML code. If you are just getting started with Help & Manual it is advisable to only use the Simple Template Layout tab. This allows you to use the default template while you are getting used to the program.

For full details on all the settings in this section see HTML Page Templates in the Reference section.

Topic content:

The most important thing to know about topic page templates is that your final HTML pages are made by combining code of the template with the contents of the topics edited in Help & Manual. In HTML terms, the content from the editor is everything between the <body> and </body> tags, the HTML template provides everything else.

The content of your topic is inserted in the template at publish time by the variable <%TOPIC_TEXT%> in the template. When you compile, the HTML page is created by replacing this variable in the template with the content of the current topic.

The topic header:

The topic header is also generated by the template. It is created by the code between the <IF_TOPIC_HEADER> and </IF_TOPIC_HEADER> conditions. (These condition tags are always stripped out before your project is published. The output code contains no proprietary tags.)

You can add material to the header on every topic page by adding text, links images etc. between these condition tags. The contents of the header box from the editor is inserted with the variable <%TOPIC_HEADER%>.

Creating "headers" and "footers":

You can create "headers" and "footers" in the body of your topic by editing the HTML template and adding material above and below the <%TOPIC_TEXT%> variable. Everything above this variable will be a header, everything below it will be a footer. This can also be done in the Simple Template Layout tab, which provides text entry boxes for this purpose.

The <%TOPIC_BREADCRUMBS%> variable can be used to create a "breadcrumb trail" of navigation links to the topics above the current topic in the TOC tree. This can be useful for showing the user where they are.

For example, if the current topic is The Editor in the sequence Introduction > About the Program > User Interface > The Editor, inserting the <%TOPIC_BREADCRUMBS%> variable would create this series of links in your output (note that the current topic is not included):

Introduction > About the Program > User Interface

The links are active, i.e. clicking on them will take the user to the referenced topics. For example, this feature is used to create the breadcrumb trail of links above the headers in the HTML Help and Webhelp versions of this help.

How to insert a breadcrumb trail:

These instructions show you how to insert a breadcrumb trail at the top of the topic text, directly below the header.

1.	Select the Default template in Configuration > HTML Page Templates and locate the following code:

<table width="100%" border="0" cellspacing="0" cellpadding="5">
<tr valign="top"><td align="left">
<%TOPIC_TEXT%>
</td></tr></table>

2.	Add the following code (highlighted in blue):

<table width="100%" border="0" cellspacing="0" cellpadding="5">
<tr valign="top"><td align="left">
<IF_TOPIC_BREADCRUMBS><p style="font-size: 8pt; margin-bottom: 15px">
<%TOPIC_BREADCRUMBS%> > Editing HTML templates</p></IF_TOPIC_BREADCRUMBS>
<%TOPIC_TEXT%>
</td></tr></table>

The <IF_TOPIC_BREADCRUMBS> condition ensures that the trail is only inserted where it is relevant. (The breadcrumbs variable is empty in top-level topics and in all topics in the Invisible Topics section.)

If you want you can also use <IFNOT_TOPIC_BREADCRUMBS> to insert alternative content to be displayed in top-level topics.

Note that the title of the current topic is not included in the <%TOPIC_BREADCRUMBS%> variable because it may not be needed if the topic title is visible directly above the breadcrumb trail. In our example we have included the current topic title with the Editing HTML templates variable to show how it is done. (The > code inserts the > character, which could otherwise be misinterpreted by some browsers.)

For more details on variables and output conditions in HTML templates see HTML template variables and HTML template output conditions.

Breadcrumb trail without active links:

If you need to create a breadcrumb trail without active links you can do this with the More Advanced Procedures > Using HTML Templates > Editing HTML templates variable. This is almost the same as the breadcrumbs variable but it creates no links and also includes the title of the current topic. See HTML Template Variables for details.

Have you tried clicking the green "home" button in the header of this help? Instead of taking the user rigidly to the default page of the help it automatically links to the parent chapter of the current topic, if there is one. If the current topic doesn't have a parent chapter (for example if its top chapter is a chapter without text) the link will automatically take the user to the project's default topic.

You can do this with the variable <%HREF_PARENT_CHAPTER%>. Just use this variable instead of the <%HREF_DEFAULT_PAGE%> variable in your topic page template. Everything is automatic – when you compile the correct links are generated automatically to the parent chapter or the default topic, depending on whether a parent chapter is available or not.