More Advanced Procedures > Using HTML Templates > Script and CSS components for experts

This topic is only relevant for users with extensive HTML, CSS and JavaScript coding experience. It explains how the standard script and other references are managed in the various templates and how you can manipulate them for your own needs.

Key Information

Note that all these instructions also apply for templates in skin files. Skins contain the same templates as normal projects, in the same locations.

Script components used in the templates

Help & Manual uses the jQuery JavaScript framework in CHM and WebHelp output for more efficient JavaScript coding and effects. The compressed version of the latest jQuery script file is exported and referenced automatically in the templates. There are also additional CSS script files included by Help & Manual for layout and dynamic functions. If you are familiar with HTML, CSS and JavaScript coding, you can change the positions of the references to these files, leave them out entirely or write your own modified versions of the style definitions and functions they contain.

The WebHelp Layout template contents depend on the layout option chosen

The contents of the layout template change depending on whether you choose "Integrated", "Classic 2 Frames" or "Classic 3 Frames" in Configuration > Publishing Options > WebHelp > Layout. In the Integrated version, HTML5 is used and the topic and navigation pages are loaded in modern iFrames. The Classic versions use a traditional frameset (now deprecated) and load the topic and navigation pages into conventional frames. The same JavaScript files are used in all three versions, however.

The "No Frames" option disables the Layout template

The layout template is not used at all if you choose the "No Frames" option. Then the Table of Contents template is set as the main index.html file and the contents of the layout template are irrelevant for your output because the template is not present.

HTML Topic Page templates are (almost) always used.

The topic page templates in Configuration > HTML Page Templates are used by almost all HTML-based output formats (CHM, WebHelp, EXE eBooks and Visual Studio Help 2008 and 2010). The Topic Page Template contains a script that automatically loads the full WebHelp user interface if a topic is opened on its own (for example from a search engine link) but you can turn this off if you want.

Exception: iBooks/ePub
The only exception is the Apple iBooks/ePub eBooks format, which uses a special hard-wired topic page template that cannot be edited. The requirements for ePub in general and iBooks in particular are so strict and specialized that this template should not be edited and is not generally accessible. (If you really want to bite the bullet and design your own topic page template for ePub send us a mail and we will help you out. There is an undocumented way to do this...)

The WebHelp Table of Contents, Index and Search templates are always the same

The contents of the WebHelp Table of Contents, Index and Search templates remain unchanged no matter which layout option you choose. They are just loaded into different frames depending on your layout choice.

If you choose the "No Frames" option The TOC template is used as the main index.html file. It contains script that identifies whether it is loaded in a frame or on its own and responds accordingly.

There are some additional special switches and options you can use to get more control over your HTML output in WebHelp.

Normally, Help & Manual writes a certain amount of inline CSS style code in the TOC elements so that our own scripts can manage the functionality of the TOC better. However, you can turn this off completely if you want full control over the TOC formatting for your own purposes.

To do this you just need to insert the following special comment anywhere in the <head> section of the TOC template page:

Insert it exactly as shown above, with no spaces and on a single line of its own. This will export the entire TOC tree without any inline CSS styling.

Normally, Help & Manual will include a JavaScript "redirect script" on every topic page. If the topic page is opened on its own, this script automatically loads the page in the entire WebHelp user interface with the table of contents, index etc. This is primarily designed for search engine links at Google, Bing and so on, to ensure that they don't wind up loading orphaned pages.

If you want full control over how your pages behave when opened on their own yourself, for example with your own scripts, you can turn this off. Just go to Configuration > Publishing Options > WebHelp > Navigation and deselect the check box by the option "When a topic is loaded outside the navigation frame, force it to reload the navigation frame".

Normally the keyword index is exported as a combination of <div> and <table> elements and the formatting is handled automatically by Help & Manual. If you want to control it entirely yourself you can insert a switch that will tell Help & Manual to export the keyword index as a list box (<select> element with <option> elements). Note that when you do this you must also provide your own JavaScript and CSS code for managing the index! On its own, the list box is as dead as a doornail!

To do this you just need to insert the following special comment anywhere in the <head> section of the Keyword Index template page:

Insert it exactly as shown above, with no spaces and on a single line of its own. This will export the keyword index and its contents as a list box that you can style and manage as you like.

The template in Configuration > Publishing Options > WebHelp > Layout defines the main index.html file in your WebHelp output if you are using one of the integrated layout options. If you choose the No Frames option the Table of Contents template is used for the main index.html file and the contents of the Layout template are not used at all. This template is then not relevant.

CSS components:

The CSS stylesheet generated from the styles defined in your project is referenced in the Layout template with this line of code:

This reference is not strictly required in the layout template and you may be able to remove it if none of your project styles are referenced in the template. If you want to redefine or extend any styles referenced there simply place an include for your own stylesheet or your own inline style code directly after this reference. Store your .css stylesheet file in the Baggage Files section of your project, then it will be exported automatically.

In addition to this there is inline CSS code for the components of the layout file itself. You can edit this if you want, but the results are entirely your responsibility.

Referenced script files:

The following three files are referenced in index.html file.

jquery.js	The jQuery script file containing all the jQuery functions.
helpman_settings.js:	Settings and configuration variables used by Help & Manual's scripts.
helpman_navigation.js	Functions used in the main layout page for the table of contents and dynamic layout features.

Changing the positions of the main script files

The three script files (jquery.js, helpman_settings.js and helpman_navigation.js) can be inserted as a block using the following special script include with the <%NAVIGATION_SCRIPT%> variable for the source .

To control the position of all three files together just place the above line in the place where you want them to appear. If you want to control them individually do not use the above line or the <%NAVIGATION_SCRIPT%> variable. Instead, add the lines individually in the places where you want them to appear.

If you don't use the <%NAVIGATION_SCRIPT%> variable Help & Manual will not insert any of these lines automatically. So you can exclude any of the files in this template by not using the variable and leaving out the include of the file you don't want to use.

Don't try to use both the <%NAVIGATION_SCRIPT%> variable and the explicit includes! If you do, you will get double entries!

Using your own version of jQuery

If you want to use a different version of jQuery for any reason, you can. Just save it in the Baggage Files section of your project and make sure that the file is called jquery.js, then it will overwrite the version exported by Help & Manual. If you want you can also include your own version with a different name and reference it in your own include line.

Redefining functions in the scripts

If you want to redefine any of the functions in the existing scripts just define your own versions in scripts added inline or with includes after Help & Manual's own versions, referencing Help & Manual's scripts explicitly as shown above so that they come first. If you use a script file rather than inline code put it in your Baggage Files section, then it will be exported automatically.

Use the variable syntax without the "var" identifier (you're redefining functions that already exist!) to redefine any functions, like this:

functionName = function(arg1, arg2, ...) {

your code here...

}

The template(s) (you can define multiple page templates) in Configuration > HTML Page Templates define(s) the HTML pages into which the rendered contents of your topics are inserted when you publish your project to an HTML-based output format. This is CHM, WebHelp, EXE eBooks and Visual Studio Help 2008 and 2010 but not Apple iBooks/ePub. The ePub output uses a special hard-wired template that cannot be edited.

CSS components:

The CSS stylesheet generated from the styles defined in your project is referenced in the HTML topic page template with this line of code:

This reference is essential for the proper formatting of your topic content as designed in the Help & Manual editor! If you want to redefine or extend any styles referenced there simply place an include for your own stylesheet or your own inline style code directly after this reference. Store your .css stylesheet file in the Baggage Files section of your project, then it will be exported automatically.

Referenced script files:

The following four files are referenced in topic page templates.

jquery.js	The jQuery script file containing all the jQuery functions.
helpman_settings.js:	Settings and configuration variables used by Help & Manual's scripts.
helpman_topicinit.js	Functions used to initialize the topic pages and provide additional functionality there.
highlight.js	This file is used by the Wrensoft Zoom full-text search engine for WebHelp to provide highlighting for the search results if you have activated highlighting. It is inserted and referenced automatically and you can't change its position. It should be considered to be hard-wired and off limits.

Changing the positions of the main script files

If the template does not already contain includes for the main script files (jquery.js, helpman_settings.js and helpman_topicinit.js) the include lines are inserted automatically. If you want to change the positions of the main script files you just need to insert the include lines in the template yourself in the position where you want them to appear. For example, you may want to make sure that the jQuery reference comes before some functions of your own that include jQuery:

If these includes appear anywhere in the <head> section Help & Manual will not insert its own versions.

Using your own version of jQuery

If you want to use a different version of jQuery for any reason, you can. Just save it in the Baggage Files section of your project and make sure that the file is called jquery.js, then it will overwrite the version exported by Help & Manual. Also, any include whose src= attribute starts with the characters "jquery" will also prevent Help & Manual from writing its own include line for jQuery, so if you want you can also include a version with a different name.

Redefining functions in the scripts

Use the variable syntax without the "var" identifier (you're redefining functions that already exist!) to redefine any functions, like this:

functionName = function(arg1, arg2, ...) {

your code here...

}

The template in Configuration > Publishing Options > WebHelp > Table of Contents defines the contents of the table of contents page in WebHelp.

Without frames, the TOC is the main page

This page is used in two different ways, depending on which layout option you choose in the Layout template. If you choose "Integrated" or "Classic 2-Frame" or "Classic 3-Frame" the TOC page is loaded into an iFrame or conventional frame in the main index.html page defined by the layout template. If you choose "No Frames" the layout template is not used and the TOC page is used as the main index.html page. The page contains script that checks whether it is in a frame or being opened on its own.

CSS components:

The CSS stylesheet generated from the styles defined in your project is referenced in the HTML topic page template with this line of code:

This reference is not strictly required in the TOC template and you may be able to remove it if none of your project styles are referenced in the template. If you want to redefine or extend any styles referenced there simply place an include for your own stylesheet or your own inline style code directly after this reference. Store your .css stylesheet file in the Baggage Files section of your project, then it will be exported automatically.

Special CSS components for the TOC list:

The actual CSS that controls the layout of the TOC itself is only used in this page and it is thus inserted as inline code. The first lines simply define the text formatting of the text levels (.heading1 - .heading6 – if you have more than 4 levels in your TOC you are doing something badly wrong). This is then followed by this extremely important block of code:

/* TOC LIST CSS */
#toc { padding: 0; margin: 0; }
#toc li { margin-top: 2px; }
#toc ul { padding-left:0; }
/* TOC LIST CSS */

If this block is not present inline formatting is generated!!
The TOC is exported as an unordered UL list and this block defines the formatting of the list components. The /* TOC LIST CSS */ comment lines at the beginning and end of this block are crucial: If these lines are present, Help & Manual assumes that you are controlling the TOC formatting with the style definitions here. If these lines are not present the TOC list will be generated with inline styles that will make it impossible to adjust its formatting with additional CSS.

Referenced script files:

The TOC is a special case when it comes to script file references. In the frame-based layout options (Integrated and the Classic frame layouts) all the TOC manipulation is performed from the main layout page. There are calls to functions in the TOC, but they reference scripts in the parent layout page. There are thus no direct includes for the jQuery and other script files in this page.

If the TOC is opened on its own without the layout page (No Frames option, or the user opens the TOC directly) the initialization script in the TOC page identifies this and loads the following three scripts dynamically:

jquery.js	The jQuery script file containing all the jQuery functions.
helpman_settings.js:	Settings and configuration variables used by Help & Manual's scripts.
helpman_navigation.js	Functions used to initialize the topic pages and provide additional functionality there.

Loading the main script files yourself

If for any reason you want to reference any of the main script files yourself you can do this with standard includes entered in the template code:

If you do this, Help & Manual will automatically remove the dynamic load options for the script files you reference from the code it generates. You are most likely to need to do this with jQuery, if you want to use your own jQuery functions within the TOC page, for which you will need an instance of jQuery inside the page's own namespace. But you may also want to have access to the variables in the settings file or force a specific position for the navigation file in the template code for cases where the TOC is loaded on its own.

Doing this will not interfere with the functioning of Help & Manual's own TOC code. If the parent layout page is present, the navigation functions in the layout page's instance of the script will still be used automatically.

Using your own version of jQuery

If you want to use a different version of jQuery for any reason, you can. Just save it in the Baggage Files section of your project and make sure that the file is called jquery.js, then it will overwrite the version exported by Help & Manual. Also, any include whose src= attribute starts with the characters "jquery" will also prevent Help & Manual from writing its own dynamic load line for jQuery, so if you want you can also include a version with a different name.

Redefining functions in the scripts

Use the variable syntax without the "var" identifier (you're redefining functions that already exist!) to redefine any functions, like this:

functionName = function(arg1, arg2, ...) {

your code here...

}

The template in Configuration > Publishing Options > WebHelp > Keyword Index defines the contents of the Keyword Index pane file in your WebHelp output. If you are using the integrated layout option the page is loaded into the navigation pane iFrame when the user views the Index (or into the navigation pane frame if you are using one of the classic layouts).

CSS components:

The CSS stylesheet generated from the styles defined in your project is referenced in the HTML topic page template with this line of code:

This reference is not strictly required in the index template and you may be able to remove it if none of your project styles are referenced in the template. If you want to redefine or extend any styles referenced there simply place an include for your own stylesheet or your own inline style code directly after this reference. Store your .css stylesheet file in the Baggage Files section of your project, then it will be exported automatically.

In addition to this there is inline style code that defines how the components of the keyword index are displayed. You can edit these styles if you wish to achieve your own results.

Referenced script files:

The following two files are referenced in keyword index template.

jquery.js	The jQuery script file containing all the jQuery functions.
helpman_settings.js:	Settings and configuration variables used by Help & Manual's scripts.

Changing the positions of the script files

The script files (jquery.js, and helpman_settings.js) are inserted automatically at the end of the <head> section if they are not referenced explicitly in the template code. If you want to change the positions of the includes just add the following explicitly in the places where you want them to appear. Help & Manual will then not add them automatically.

Using your own version of jQuery

Redefining functions in the scripts

Use the variable syntax without the "var" identifier (the functions already exist!) to redefine existing functions, like this:

functionName = function(arg1, arg2, ...) {

your code here...

}

The template in Configuration > Publishing Options > WebHelp > Full Text Search defines the contents of the Full Text Search pane file in your WebHelp output. If you are using the integrated layout option the page is loaded into the navigation pane iFrame when the user views the Search (or into the navigation pane frame if you are using one of the classic layouts).

CSS Components:

The CSS stylesheet generated from the styles defined in your project is referenced in the HTML topic page template with this line of code:

This reference is not strictly required in the search template and you may be able to remove it if none of your project styles are referenced in the template. If you want to redefine or extend any styles referenced there simply place an include for your own stylesheet or your own inline style code directly after this reference. Store your .css stylesheet file in the Baggage Files section of your project, then it will be exported automatically.

In addition to this there is inline style code that defines how the components of the search components are displayed. You can edit these styles if you wish to achieve your own results. Do so with care, because the search components are quite finicky.

Tip: If you find that you are unable to get line spacing to do what you want in the search components this is because the Wrensoft Zoom search engine is doing quite a bit of line spacing with hard <br /> tags. The only way to deal with this is to analyze the generated code with a tool like Firebug and use JavaScript to remove these hard breaks on the fly.

Referenced script files:

jQuery is not used by default in the Search page. Also, the entire "script" package is inserted by the <%SEARCH_SCRIPT%> variable and all its components should normally be in the same place. If you leave this variable out you must do everything manually. The following two files are referenced in keyword index template.

zoom_search.js	The Wrensoft Zoom search engine script.
helpman_settings.js:	Settings and configuration variables used by Help & Manual's scripts (may also contain search settings).

Changing the position of the script files

Normally you would only change the position of the entire search script block by adjusting the position of the <%SEARCH_SCRIPT%> variable. If you want to leave it out for any reason you should study the normal output carefully and insert everything manually.