This article is a guide to customizing the default WebWorks Help 5.0 template supplied with WebWorks ePublisher Pro (WWeP). The default template is functionally complete, but I had to customize it to match the look and feel of TSX SecureFile, a web-based tool that allows listed issuers to file securities documentation with TSX. During the course of developing the template, I found out quite a bit about WWeP that isn't covered in the documentation, and I'll share those tips in this article.
Because SecureFile is a web-based product, I chose the WebWorks Help format for its online help. WebWorks Help runs in a web browser. It has a dynamic table of contents, an index, and full-text search. WebWorks Help requires that the user have JavaScript enabled in his or her browser. This was't an issue for me, as SecureFile also requires JavaScript.
I decided to create a new WWeP template from scratch, rather than migrating my WebWorks Publisher 2003 template, because several users on the wwp-users Yahoo Groups mailing list have reported problems with templates migrated from WWP 2003.
In this article I'll describe the settings that I had to modify from the WWeP defaults and any other customizations that I made outside of the WWeP interface. Instructions for some of the modifications are available in WWeP's documentation and the support knowledgebase on Quadralay's web site. I also gathered some information from questions posted on the wwp-users mailing list. The wwp-users list is an essential resource and I recommend it highly.
Unless otherwise noted, all directories and files are relative to the project directory.
You use the Style Designer module of WWeP to modify paragraph and character styles, cross-references, and so on. In practice, most of the modifications you have to make to a template are to paragraph styles.
WebWorks ePublisher takes a different approach from WebWorks Publisher 2003, where you had to map your styles to the pre-defined WebWorks styles. Instead, WWeP creates a paragraph style for each FrameMaker paragraph style, with the same name as the FrameMaker style. It is possible to create paragraph styles and have children styles under those, so a child paragraph takes on the attributes of the parent style. By grouping your styles under parent styles, you can reduce the number of styles you have to customize. For example, in my template, I grouped all of the heading styles under a headings_base style.
WWeP picks up its paragraph settings from the FrameMaker source files. It usually does a good job of matching the online format to the printed document. The amount of customization you will need to do depends on the design of your online help. I was able to leave most of the body text styles alone, and just modified headings and a few other styles.
These are some changes you might need to make:
The only change I needed to make to the character styles was to set the colour of the text for the character style I had defined for references to glossary topics.
WWeP gives you a lot of control in how you want to format tables. In my case, I didn't have very many and opted for a plain style with no borders. I did find that WWeP puts more space between rows than I would like, but I haven't yet figured out how to reduce it. WWeP uses the CSS table model to control table formatting. The online help discusses this in some detail – it is moderately complex.
WWeP lets you create styles for different types of HTML pages. I only needed one new page style, to be used to display popups. The settings I used were:
Default page
Popup
The Format menu in WWeP lets you control which conditional text and variable definitions you want to appear in your document and set cross-reference rules. There's also a Format Settings item that lumps together settings for company information, accessibility, PDF output, and so on. Some of the items in the Format menu in WWeP were under the Style Designer in WWP 2003.
In my template, I used PrintOnly, HelpOnly, and Comments conditionals. You use the Format menu's Conditionals dialog box to set the conditionals that you want to appear in your document. WWeP is supposed to ignore the settings in the FrameMaker file, but I found that sometimes it followed the setting in the FrameMaker file and not ones I'd set in WWeP, so it's probably best to make your settings in FrameMaker match what you want in the WWeP output.
The Format menu's Variables dialog box lets you override the definition of variables that are set in the FrameMaker document. I had some trouble with this feature, as I made changes to my variable settings in FrameMaker that weren't picked up by WWeP, because I had't explicitly set them in WWeP. There's been some controversy on the wwp-users mailing list about this feature – the consensus seems to be that it's poorly implemented.
Cross references in WWeP work the same way they did in WWP 2003. You can have different cross-reference settings for PDF and online output, if you use WWeP to create PDFs. (I don't.)
Use the Format Settings dialog box to control PDF output, company information, locale, and some file name and accessibility settings. Some of these were under Project Options in WWP 2003.
If you're creating WebWorks Help, you can use the Format Settings dialog to choose skins, which are predefined layouts with different colours and button styles. There are about 15 included with WWeP. I created a format override (following in instructions on Quadralay's knowledge base), on the Classic skin, as it was the closest in appearance to the original WWP 2003 template.
Despite the many options in WWeP's new interface, you'll find that you have to make some customizations manually by editing files.
I used the Toronto Stock Exchange logo in contents pane of my pages. I had to size it manually in Paint Shop Pro, because it doesn't appear possible to set the image size in the interface. You must place the logo in the Files subdirectory, and not in the images subdirectory under Pages.
I also used the TSX logo for the splash screen. I named it splash.jpg, and copied it to Formats\WebWorks Help 5.0\Skins\Classic\wwhelp\images.
I used the navigation buttons form my WWP 2003 template, which I had edited in Paint Shop Pro to match the colours in SecureFile. I copied the buttons from the previous version of the template into Formats\WebWorks Help 5.0\Skins\Classic\wwhelp\wwhimpl\common\images.
The navigation bar frame background colour is controlled by the file Formats\WebWorks Help 5.0\Skins\Classic\wwhelp\wwhimpl\common\images\toolsbg.gif, This file was divider.gif in WebWorks Help 4.
The Contents, Index, and Search tabs are created from several smaill .gif files which reside in Formats\WebWorks Help 5.0\Skins\Classic\wwhelp\wwhimpl\js\images\. To change the foreground, backgrounmd, and border colours of these tabs, you must edit the following files in a graphics editor.
To change to colour of the table of contents pane, edit viewbg.gif in a graphics editor. You may need to edit each of the 27 colours in the file's colour palette. In my case, I wanted a white background, and I had to change 15 shades of grey to white.
The procedure to create popups, as documented in the WWeP Help, is a lot of work, because you need to apply two markers and a character style for each popup link. As it turns out, the procedure used in WWP 2003 still works and is much simpler – you just need to apply a character style for the popup link. You will need to create paragraph styles for the glossary definitions that the popup windows display – this procedure is described in the online help and is the same as it was in WWP 2003.
In WWP 2003, you had to make many manual changes to the normal.asp file. In WWeP, the equivalent file is page.asp, which has the location \Formats\Microsoft WebWorks Help 1.x\pages.
page.asp is the file that controls the layout of the topics frame. Despite the .asp extension, this is an XML file and can be edited with a standard text or XML editor. I made several changes to this file.
If you modify page.asp manually, there are a couple of things you must watch out for.
Location: Formats\Microsoft WebWorks Help 1.x\css
Modify this style sheet to provide additional control of formatting in the help system. WWP uses values from this file and the values from the Style Designer to control the formatting of the output.
If you want to change the style or colour of hyperlinks in WWeP, you need to edit the link styles in this style sheet.
WWeP also creates a style sheet for each input FrameMaker file, to handle changes that you make in the Document Designer. If you don't use the Document Designer (and most WWeP experts think that you shouldn't), you can ignore these files.
This file is analogous to settings.txt in WWP 2003. Edit the file in the format override directory, not the one in the directory for the original skin. It appears that settings made in the Format Settings dialog box override manual edits to this file. I turned off the Favorites tab in the file, but it stayed visible until I turned it off with the Format Settings dialog box. In this file, you can manually edit the values for the font used in the tabs of the table of contents pane. I changed the font colours by editing these lines:
<Tabs>
<DefaultColors
foreground="#FFFFFF" />
<SelectedColors foreground="#666666"
/>
</Tabs>
I also edited the colours for the mouse-over text in the table of contents. The settings are in the <hover text> element.
Most of the major bugs have been fixed in maintenance releases. However, there are still a few things to watch out for.
I started working on this template with an early release of WebWorks ePublisher. I had hoped to use it for the release of the latest version of SecureFile in January, but decided to stick with WWP 2003, because of the number of bugs I encountered when setting up the template. However, the last couple of releases have cleared up most of the problems that I encountered, and I consider version 9.1 to be usable for a production release. I will be moving my existing WWP 2003 projects over to WebWorks ePublisher as time permits.
Keith Soltys has been working as a technical writer for 18 years, and is currently at the Toronto Stock Exchange. He maintains the Internet Resources for Technical Communicators web site as well as a weblog. He lives in Pickering with his wife, two children and their cat.