Updating Topic Templates and Icons

Help Builder's topic rendering relies on a template engine that handles the base layout for the overall page, and then for individual topics. The template engine also manages some of the page script logic and overall styling, all of which can optionally be customized. The engine is based on plain Web technologies: HTML5, CSS and JavaScript and the markup, stylesheets and script code are all available for modification.

New Versions often update Templates

When a new Help Builder version ships, quite frequently the stock templates are updated as well. Most of the time the changes are minor and have little effect on the page layout other than minor graphical updates. But in some cases the changes might incur changes that affect behavior. These are outlined in the release history.

Updating your Templates

If you are using stock templates without modifications, then you can simply update your templates, and things will continue to work. To do this use the Update Templates option on the Options dialog:

When you click the button your stock templates will be updated to the new stock versions, overwriting whatever previous templates existed.

Help Builder also creates a backup of your old templates in a folder called TemplateBackup_<datetime_stamp> that backs up all of your current templates, so you can review and compare the new templates to the old.

Help Builder also creates a _layout_old.wcs copy of _layout.wcs which is the master page template for your topics and where most of the styling changes you might make are applied. You can then use a comparison tool like Beyond Compare or WinMerge.

Updating customized Templates

If you are using custom or customized templates, then updating to new templates is likely a bit more involved.

You start by updating your templates just as described above to get the latest versions.

Since Help Builder creates a copy of the templates, you now can compare the old and new templates and decided whether you need to use the new changes or keep the old version of yours.

How much work this is really depends on whether you make minor changes or whether you completely replace the existing templates.

Most people are likely to stick to minor changes that typically involve:

• Changing the icon image at the top by replacing logo.png
• Making minor changes in _layout.wcs to change overall appearance
• Customizing colors and fonts in wwhelp.css
• Customizing the table of contents tableofcontents.wcs

In most cases the format of most of the topic related files doesn't change. They all have a common layout format and typically don't change.

If you're anything like me I change _layout.wcs with my company name and the proper documentation feedback link. I sometimes make a few very minor changes in wwhelp.css to tweak font sizing or coloring usually related to the header of the page.

All of these changes are easy to manage with a comparison tool like beyond compare, which shows you all changes at a glance and lets you apply the changes as needed.

For example, in the following screen shot I edit my compare _layout.wcs against the old _layout_old.wcs file:

You can see that the old page had a company name and email address as well as Google Analytics code to help with site stats for the Web site. Using BeyondCompare it's easy to push these old custom values into the new template. The same approach is used for comparing wwhelp.css and tableofcontents.wcs.

If you have extensively customized Templates or new Themes...

If you have more complex changes or you created a brand new theme, then your work will be more involved as you have to compare your templates to the new templates and compare each one.

The most important thing in terms of making sure your templates work is making sure that the overall structure in _layout.wcs is maintained - and especially the page-content, toc and main-content classes as Help Builder uses these to inject topics and TOC info dynamically at runtime while navigating.

Maintaining the overall document structure is important in order for Help Builder rendering to continue to work even when customizing the templates heavily.