Controlling the TOC with wwhelp

Controlling the TOC with wwhelp_books.xsl

Last Modified: June 26, 2006

ePublisher Pro

The purpose of this article is to explain the function of wwhelp_books.xsl and how to modify it to achieve certain appearance effects.

This XSL file is called by the ePublisher Pro engine during a WebWorks Help 5.0 transform. It is instrumental in organizing the top-level groups in a project and it is responsible for creating the books.xml file that controls certain aspects of how the output for each group is displayed.

Editing wwhelp_books.xsl

To build a Table of Contents, your output is organized into books based on the top-level groups specified in the Document Manager. wwhelp_books.xsl uses settings defined by the user to name and display these books.

Before you begin making changes outside the GUI, you must first perform a project format override on wwhelp_books.xsl. For more information, see Creating Project Target Overrides. The default location of wwhelp_books.xsl is in the ePublisher Pro installation directory \ePublisher Pro\Formats\WebWorks Help 5.0\Transforms\

You can make the following changes to your output by editing wwhelp_books.xsl. Click on each to view an explanation and a procedure.

Define the Text in the browser title bar when your help system is first launched

Specify whether a book is shown for the top-level group(s)

Specify whether top-level books are expanded when your help system is launched

Define the Text in the browser title bar when your help system is first launched

By default, the text in the title bar is derived from the name of the top-level group for single-group projects, and from the “Merge Title” setting in the Merge Settings dialog box (Format>>Merge Settings) for projects with multiple top-level groups.

To change the title for a single-group project

You may specify browser title text for a project by changing the name of the top-level group in the Document Manager. You may also assign a unique title by making a change in wwhelp_books.xsl. This is helpful if, for example, you want to use stationery to define the title text for multiple projects. Follow these steps to change the title text:

1)	Open the copy of `wwhelp_books.xsl` created with the project format override above.

2)	Find the following line of code:

<wwhbooks:WebWorksHelpBooks version="5.0" name="{$VarTitle}" expandalltopentries="false" showbooks="false">

3)	Replace the value `{$VarTitle}` with your desired title text.

Example:

<wwhbooks:WebWorksHelpBooks version="5.0" name="New Title Text" expandalltopentries="false" showbooks="false">

4)	Save `wwhelp_books.xsl` and Regenerate your output.

Result:

Text of browser window is replaced

To change the title for merged help (more than one group)

You may specify browser title text for a merged help project by changing the “Merged Title” setting in Merge Settings. If no title is specified by the user, the name of the project format will be used as the title (example: “WebWorks Help 5.0”). You may also assign a unique title by making a change in wwhelp_books.xsl. This is helpful if, for example, you want to use stationery to define the title text for multiple projects. Follow these steps to change the title text:

1)	Open the copy of `wwhelp_books.xsl` created with the project format override above.

2)	There are two ways to change the title text:

a)	To change the title used if no value exists in Merge Settings:

•	Find the following line of code:

<xsl:value-of select="wwprojext:GetFormatName()" />

•	Replace the value `wwprojext:GetFormatName()` with your desired title text, surrounded by single quotes.

Example:

<xsl:value-of select="‘My Merged Title’" />

a)	To change the title and override any value in Merge Settings:

•	Find the following line of code:

<wwhbooks:WebWorksHelpBooks version="5.0" name="{$VarMergeTitle}" expandalltopentries="false" showbooks="true">

•	Replace the value `{$VarMergeTitle}` with your desired title text.

Example:

<wwhbooks:WebWorksHelpBooks version="5.0" name="My Merged Title" expandalltopentries="false" showbooks="true">

2)	Save `wwhelp_books.xsl` and Regenerate your output.

Result:

Text of browser window is replaced.

Specify whether a book is shown for the top-level group(s)

For a project with only one top-level group, the book created for that group is hidden by default, and the contents of that group are displayed. A project with merged output will display a book for each top-level group by default. This setting can be toggled by editing wwhelp_books.xsl.

To show a book for a single top-level group

You may wish to display a single book in the TOC of your help set. This can be helpful if you want to give your users a simple starting point from which to navigate.

1)	Open the copy of `wwhelp_books.xsl` created with the project format override above.

2)	Find the following line of code:

<wwhbooks:WebWorksHelpBooks version="5.0" name="{$VarTitle}" expandalltopentries="false" showbooks="false">

3)	Change the value of the attribute `showbooks` from `false` to `true`.

4)	Save `wwhelp_books.xsl` and Regenerate your output.

Result:

A book is shown for the single top-level group

To hide the top-level books in a merged help system

If you have several groups in the Document Manager, you may not want them to appear as separate books in the TOC of your output. This can be helpful if you use groups for organizational purposes only and want your output to flow together seamlessly.

1)	Open the copy of `wwhelp_books.xsl` created with the project format override above.

2)	Find the following line of code:

<wwhbooks:WebWorksHelpBooks version="5.0" name="{$VarMergeTitle}" expandalltopentries="false" showbooks="true">

3)	Change the value of the attribute `showbooks` from `true` to `false`.

4)	Save `wwhelp_books.xsl` and Regenerate your output.

Result:

The book for each top-level group is hidden

Specify whether top-level books are expanded when your help system is launched

By default, the TOC is collapsed, listing the table of contents level 1 as defined in the Style Designer.

TOC books are collapsed by default

It is possible to launch your help set with all the top-level books expanded by editing wwhelp_books.xsl. This setting can be applied to projects with one or more groups, and it will only affect the uppermost books in the TOC hierarchy.

To expand all top entries in a single-group project

If an ePublisher Pro project has a single top-level group, then the book for that group is hidden and its contents become the top level of the TOC. If you wish to display this book, see Specify whether a book is shown for the top-level group(s). Follow these steps to expand the top-level books that are displayed:

1)	Open the copy of `wwhelp_books.xsl` created with the project format override above.

2)	Find the following line of code:

<wwhbooks:WebWorksHelpBooks version="5.0" name="{$VarTitle}" expandalltopentries="false" showbooks="false">

3)	Change the value of the attribute `expandalltopentries` from `false` to `true`.

4)	Save `wwhelp_books.xsl` and Regenerate your output.

Result:

Top-level books are expanded upon launch

To expand all top entries in a merged help project

If an ePublisher Pro project has multiple top-level groups, then a book is shown for each one. If you wish to hide these books, see Specify whether a book is shown for the top-level group(s). Follow these steps to expand the top-level books that are displayed:

1)	Open the copy of `wwhelp_books.xsl` created with the project format override above.

2)	Find the following line of code:

<wwhbooks:WebWorksHelpBooks version="5.0" name="{$VarMergeTitle}" expandalltopentries="false" showbooks="true">

3)	Change the value of the attribute `expandalltopentries` from `false` to `true`.

4)	Save `wwhelp_books.xsl` and Regenerate your output.

Result:

Top-level books are expanded upon launch

Summary

After performing a project format override, wwhelp_books.xsl can be edited to produce several common changes to the default appearance of your WebWorks Help 5.0 output. These changes are summarized as follows:

For Single-Group Projects
Default Code	Edit	Effect
`<wwhbooks:WebWorksHelpBooks` `version="5.0"` `name="{$VarTitle}"` `expandalltopentries="false"` `showbooks="false">`	`name="New Title Text"`	Browser window title will be “New Title Text” when help system is launched
	`expandalltopentries="true"`	When help system is launched, top-level books in the TOC are expanded.
	`showbooks="true"`	Displays a book for the top-level group.
	`showbooks="true"`	Displays a book for the top-level group.

For Multiple-Group Projects
Default Code	Edit	Effect
`<wwhbooks:WebWorksHelpBooks` `version="5.0"` `name="{$VarMergeTitle}"` `expandalltopentries="false"` `showbooks="true">`	`name=”My Merged Title”`	Browser window title will be “My Merged Title” when merged help system is launched
	`expandalltopentries="true"`	When merged help system is launched, top-level books in the TOC are expanded.
	`showbooks="false"`	Hides the top-level books in merged output.
	`showbooks="false"`	Hides the top-level books in merged output.

XHTML 1.0 CSS WAI-A