So now you've basically walked through the basics of creating a help file using the default templates that ship with Help Builder. Now let's take a look and see how we can customize our help file by changing the HTML templates and style sheets.

Currently our topics look something like this:

If you'll remember of how we create topics you know that the topic content you see in this HTML view is really made up of a bunch of different fields like the Topic title, the body of the topic and in this case some dynamic text, like the data when the topic was last changed. If you move to another topic in our help file you'll notice that it has the same formatting.

The question now is, where is all of this coming from? The answer is that the Topic Type templates are driving the display of each topic type. These HTML templates exist for every topic type you create and you can leave them all the same (using a default template wwhelp.wcs and deleting the custom template) or by creating custom versions. Most of the templates have a very similar look and feel to them for consistency's sake so if you move to another type of topic like Header you'll find that this topic pretty much looks the same as a base topic. However, this is a design choice that was made, rather than a requirement. In short you can change any of the templates to get a unique look for each topic type.

Topic templates are HTML based, so if you look at a template you'll see HTML plus some ASP like markup that embeds the actual help fields. For a list of fields that are part of a standard HTML Help topic see Topic Types. Help Builder projects are also extendable to allow for custom fields.

To manage topics you use the Topic Type and Template Editor Dialog which looks like this:

This dialog has a number of features.

• Adding, editing and deleting templates
  
• Editing the master stylesheet
  
• Switching Template Schemes
  

We'll focus on the first two here. Let's start by bringing up our topic template.

Tip
You can configure an HTML editor to use for template editing in the Properties Dialog. For example I have my templates set up to bring up the Visual Studio HTML Editor (DevEnv.Exe). To get VS to recognize WCS files as HTML files you will need to open a solution and open a .WCS file there once and use Open With... and the Set Default option to set the default editor for the .wcs file. Thereafter calling Visual Studio with a .WCS file opens the file in HTML edit mode as shown in the image below.

To bring up the template, right click on the selected Topic Type and select Edit Template. Since I have Visual Interdev setup to edit my templates I get the following view:

Note that the name of the file is TOPIC.WCS which maps to our TOPIC template type. The document is all HTML except for the yellow <% %> markup tags which are using the Help Builder COM object to dynamically pull in content from the Help Builder Project we typed into. As you can see this interface is fully programmable using Visual FoxPro code in the script tags.

Notice also the link to the stylesheet in /templates/wwhelp.css. This stylesheet is vital to proper formatting and makes it possible to change the over all look of all topics for things like background colors and fonts. More on that in a minute.

If you look back at our help topic preview you notice that the Header is displayed with a grey border around it. Let's say you don't want this any more and want all topics to simply display the header directly on the page. For good measure let's change the font color of the header too to purple (yuk!):

To do this change the code below the Topic header comment from:

<TABLE WIDTH=99% BORDER=0 BGCOLOR=#EEEEEE><TR><TD ALIGN=CENTER>
<h2><%= TRIM(oHelp.oTopic.Topic) %></h2></TD></TR></Table>

to this:

<h2 align="Center" style="color:purple"><%= TRIM(oHelp.oTopic.Topic) %></h2>

and save the file. When you go back into Help Builder now and preview a topic, notice that the grey border is gone behind the header and that it is indeed purple. If you move to another topic you'll see the same behavior as long as the topic has the same topic type.

You can do whatever you want with the topic template. You can move things around, you can add fields and you can even add your own custom fields if you extended the Help Builder file. Because templates are script pages you can also run programs inside these pages. For example, you can get all topics that match a certain filter query and then dynamically build a table from these topics. For an example on how this is done check out the ClassHeader.wcs template.

By default Help Builder's templates are all very similar and have some overlap. The default wwhelp.wcs template supports just about all fields in Help Builder, and most of the other default templates implement only those fields that are typically required by these templates. Keep in mind that you can add or remove any fields you don't want to see. You can also use code like IF statements to determine whether to display something or not.

Style Sheets - Global changes

Templates change individual topic types. In theory you could change the look of the entire help project using templates, but if you want to change the look of the document wholesale you'd be stuck with a lot of template editing and a lot of custom style attributes to code.

Stylesheets make this process easier by providing a single style sheet template that's linked into every template. The stylesheet lives in /TEMPLATES/WWHELP.CSS and if you want to use your help file on a Web site as HTML you will need to include this directory and file.

To edit the style sheet click on the Edit Stylesheet button on the Topic Type and Template Dialog's toolbar. If you have Visual Interdev or another CSS editor installed you'll see the following:

The first group of tags (HTML, H1 etc.) are the standard HTML tags and determine most of the layout of the topics. Body is the most important as it controls the main document. For example, the default template is set to use a light yellow background enforced through the body tags background color.

So let's change a couple of things and see what happens. Let's change the font to Comic, 9 pt and the background color LightGrey. Save the style sheet and preview any topic now. The topic from before with all of our changes now looks like this:

Not very pretty color scheme <s>, but it demonstrates the point. If you now move to any other topics including some of other topic types you'll notice that they too will inherit these settings.

Note that you can override the stylesheet at any level. You can use explicit styles or HTML markup in your Topic Templates, or you can even directly embed formatting information into the topic text directly. So if you wanted to markup a specific paragraph in your text:

some text here that respects the stylesheet.

<<span style="font-name:Arial;font-size:12pt;font-weight:bold">>This text will always be bold<</span>>

more text here that would respect the stylesheet.