Complete Breadcrumbs Path with Multivolume Help
If you are generating multivolume WebWorks Help 5.0 help systems, you that the default behavior does not breadcrumbs for the TOC title and the Group that you specify in your project's the Merge Settings dialog. (These settings first appeared in ePublisher 2008.4). The system creates breadcrumbs solely from the paragraphs in your Framemaker files. Using the Webworks Style Designer you can assign Table of contents level to your Framemaker paragraph styles. The following image illustrates the values in the Document Manager, the Merge Settings, and the Style Designer:
The default Webworks transforms create the following output from these settings:
To get a full breadcrumbs path that includes the values in the Merge Settings Dialog you need to create a target override for the Formats\WebWorks Help 5.0\Transforms\content.xsl file in your Webworks project. You can get the code example here: Multivolume_Breadcrumbs_V1.zip (You will also find a code example of this in the attachments for this page
Creating a contents.xsl Override and Adding in the Example Code
The example code adds some new templates and replacements for the Breadcrumbs and BreadcrumbsEntry templates. To use the example file:
If you haven't already done so, download the Multivolume_Breadcrumbs_V1.zip file to your local system.
Unzip the example code.The zip file contains a single file called Multivolume_Breadcrumbs.xsl.
Copy the original contents.xsl file to your project's Transforms directory: PROJECT_DIR\Formats\WebWorks Help 5.0\Transforms\content.xsl. The original file is in your Webworks installation directory.
Edit your contents.xsl override file you just created.
Locate the Breadcrumbs and BreadcrumbsEntry in the file. (They constitute over 100 lines in the file.)
- Delete the two entries.
Copy and paste the code in the Multivolume_Breadcrumbs.xsl file into the contents.xls file where the Breadcrumbs and BreadcrumbsEntry code used to be.
Save and close your new, custom contents.xsl file.
- Regenerate your project to see your new breadcrumbs.
The following screen capture illustrates the result of using the override:
Will this Example Code Work for My Project?
Depending on how your project is structured, the code example may work for you as is. The example works out-of-the-box with the a structure that has specified Merge Settings title and one or more groups that is followed by a consistent hierarchy of Table of contents entries spanning any number of levels from 1 to n. The following illustrates a project that meets these requirements. It has a Merge Settings that include have Merge Title set to Library Contents and a single group called Merge Group. The expected navigation is as follows:
Library Contents
- Merge Group
Table of content level 1
- Table of content level 2
Table of content level 3
- etc.
- Table of content level 2
- Merge Group
This structure is correctly converted into a complete breadcrumbs path.
If your helpset structure can have gaps,for example if certain Table of contents levels are optional like in the following example structure, you have to modify the code example. The following example illustrates a structure with gaps:
- Library Contents
- Merge Group
- Table of content level 1
- Table of content level 2
- Table of content level 3
- etc.
- Table of content level 3
- Table of content level 2
- Table of content level 2
- Table of content level 3
- etc.
- Table of content level 3
- Table of content level 1
- Merge Group
This type of structure can occur if, for example, your Framemaker files do not follow a strict heading hierarchy. For projects having a gap structure, the example includes commented code. If you need to cover cases where TOC levels might be missing in your project structure, read the comments at the lines 109 and 151 in the code example and modify the code accordingly.
Some Notes on TOCEntry Level and Separator Handling
The mechanism that emits separators between breadcrumb entries is different from the one in the original content.xsl file. While in the original approach a separator is emitted after each breadcrumb entry, in the attached code example some separators are emitted conditionally and some separators are emitted before an entry instead of after the previous entry.
This is mainly because during the processing of the merge settings the script cannot know whether there are any TOCEntry ancestors of a MergeGroup. Consider a project with the following logical structure:
TOC Title - MergeGroup - [Topic with no TOC-relevant heading, but only body text]
In such a case, the emitted breadcrumbs would have to look like this:
TOC Title > MergeGroup
Note that there is no separator after the MergeGroup. Because, when processing the MergeGroup breadcrumb entry, the script cannot know whether there is an ancestor TOCEntry, the separator between the MergeGroup and the first TOCEntry has to be emitted together with a TOCEntry. Therefore, I implemented the emission of separators as follows:
A TOC Title is always emitted with a following separator, because there is always an ancestor MergeGroup.
A MergeGroup is always emitted without a separator, because it is not known at this point of time whether there will be an ancestor TOCEntry.
A TOCEntry always has a trailing separator. It also has a leading separator, if the project is a merged project and the TOCEntry's level is 1. This separator compensates for the missing separator after the MergeGroup.
So, for a merged project with a complete TOCEntry hierarchy (levels 1 to n) the final breadcrumbs can be seen as the following logical blocks:
[TOC Title > ] [ MergeGroup] [ > TOCEntry1 > ] [TOCEntry2 > ] [TOCEntry3 > ] ...
As you can see, all necessary separators are there... If, e.g., a TOCEntry level 1 might be missing, and a TOCEntry level 2 is the direct ancestor of a MergeGroup, the commented alternative code can be used instead. The alternative code does the following:
A TOC Title is always emitted with a following separator, because there is always an ancestor MergeGroup.
A MergeGroup is always emitted without a separator, because it is not known at this point of time whether there will be an ancestor TOCEntry.
A TOCEntry has a leading separator, if the project is a merged project and the TOCEntry's level is 1 or 2. This separator compensates for the missing separator after the MergeGroup. Furthermore, the TOCEntry has a trailing separator, if the level is not(!) 1.
So, for a merged project with a complete TOCEntry hierarchy, the final breadcrumbs can be seen as the following logical blocks:
[TOC Title > ] [ MergeGroup] [ > TOCEntry1] [ > TOCEntry2 > ] [TOCEntry3 > ] ...
If in the same project there are groups that are missing a level 1 TOCEntry, the following happens:
[TOC Title > ] [ MergeGroup] [ > TOCEntry2 > ] [TOCEntry3 > ] [TOCEntry4 > ] ...
Known Issues and Limitations
There is currently one minor issue concerning conditional text in TOC-relevant headings. If you have a heading in your FrameMaker document that is partly conditionalized, e.g. "Reporting <Condition> Tool Failure </Condition> Incidents", separator will be inserted before and after the conditionalized part of the breadcrumb. E.g.: Reporting > Tool Failure > Incidents. So instead of conditionalizing parts of a heading, you should consider inserting two variants of the complete headings into your FrameMaker document and conditionalize an entire heading if applicable.
Update for 2010-11-30