Updating Topic Templates and Icons
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.
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.
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
- Making minor changes in
_layout.wcsto change overall appearance
- Customizing colors and fonts in
- Customizing the table of contents
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
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
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.
Comment or report problem with topic