Inserting the Table of Contents of a Child Collection into a Parent Collection
Microsoft Help 2 enables authors to insert the TOC of a child collection into the TOC of a parent collection.
Overview
This topic explains the markup that inserts the TOC of a child Help collection into the TOC of a master (parent) Help collection. The following table illustrates one possible integration:
Parent TOC |
+ Child1 TOC (id1) |
+ Child2 TOC (id2) |
= Combined TOC |
|---|---|---|---|
+ folder1 ++ folder1.a (id1) ++ folder1.b + folder2 (id2) + folder3 |
+ child1.a ++ child1.a.1 ++ child 1.a.2 + child1.b |
+ child2.a + child2.b + child 2.c |
+ folder1 ++ folder1.a (id1) +++ child1.a ++++ child1.a.1 ++++ child1.a.2 +++ child1.b ++ folder1.b + folder 2 (id2) ++ child2.a ++ child2.b ++ child2.c + folder3 |
Both the parent namespace and the child namespace must use run-time collection files (for example, HxC, HxT) to define their collections. These collections can contain from one to n registered titles (HxS or HxS/HxI).
Two files must be modified to insert the TOC of a child collection into the TOC of a parent collection:
The run-time HxT file for the parent collection must have an ID assigned to a node where the HxT of the child collection is expected to appear.
The HxC file for the child collection must have a matching ID assigned to a TOCDef element, which also points to an HxT file belonging to the child collection. To arrange the TOCs of child collections in the correct order, each element must have a unique ID.
A third file can be used to adjust the appearance of the merged TOC:
- The HxT file for the child collection can contain markup using the PluginStyle and PluginTitle attributes to achieve the correct layout.
Because all three files are created at authoring time, some coordination is required to ensure that the ID strings match and that PluginStyle and PluginTitle are used consistently.
Note
A parent HxT may define multiple HelpTOCNodes with the same ID. A child HxT with the matching ID is inserted into each of the HelpTOCNodes. Likewise, a child collection can contain multiple TOCDef elements with the same ID. Using IDs that are not unique precludes the ability to define the order of appearance. In such a case, each of the HxT files that the TOCDef elements reference is inserted into any HelpTOCNode that has a matching ID in the parent HxT file.
For best results:
Use unique IDs that are not too long.
Avoid using XML character entities (those using the % symbol), double quotes, and other characters that are reserved for XML. The syntax of the run-time HxT file is not enforced by a DTD. It is only checked to enforce well-formed XML.
Consider using a consistent naming convention for readability, for example:
Id="InsertTOC:<namespace>[_<HXT filename>]" Id="InsertTOC:PartnerSDK" Id="InsertTOC:PartnerSDK_partner1"
Updating the Parent Runtime HxT
The first step required to insert the TOC of a child collection into the TOC of a parent collection is to identify and mark the positions in the parent HxT file where the insertions should occur. The Id attribute of the HelpTOCNode element is used for this purpose.
When a child namespace is plugged into a parent namespace, the IDs of the TOCDef elements of the child collection are reconciled with HelpTOCNode IDs in the run-time HxT file of the parent collection. If a match is found, the HxT with a matching ID that is specified in the TOC of the child collection is inserted into the parent TOC.
Insert a TOC node by using the Id attribute value, as shown in the following example:
<HelpTOCNode Id="InsertTOC:vcedit" NodeType="TOC"/>
It is still possible to specify a URL that points to a registered title or topic in the parent or plugged-in namespace, as shown in the following examples.
Using the URL attribute value to reference a registered namespace:
<HelpTOCNode NodeType="TOC" Url="vcedit"/>Using the URL attribute value to reference an individual topic:
<HelpTOCNode NodeType="Regular" Url="/vcedit/howtouse.htm"/>Note the following limitations:
If the URL attribute value is present, the Id attribute value is ignored.
The Id attribute value must conform to the rules of MSXML for CDATA attributes.
ID strings are case-sensitive ("MyID" != "myid").
Updating the Child Collection HxT
The second step required to insert the TOC of a child collection into the TOC of a parent collection is to add an ID to the child-collection TOC(s). The Id attribute of the TOCDef element is used to identify the nodes to insert.
When a child namespace is plugged into a parent namespace, the IDs of the TOCDef elements of the child collection are reconciled with IDs in the runtime HxT file of the parent collection. If a match is found, the HxT specified in the TOC of the child’s collection is inserted into the parent TOC at the node with the matching ID.
The markup for the TOCDef element is as follows:
<TOCDef Id="TOC_01" File="/main/Runtime.HxT" />
Note the following limitations:
The Id attribute value must match an ID specified in a HelpTOCNode of the run-time HxT file of the parent collection.
The File attribute value must reference a valid run-time HxT file for the child collection.
The Id attribute value must conform to the rules of MSXML for CDATA attributes.
ID strings are case-sensitive ("MyID" != "myid").
Adjusting Folders and Merging the TOC
The PluginStyle and PluginText attributes of the HelpTOC element of the HxT file of the child collection can be modified to adjust the layout of the merged TOC.
If the value of PluginStyle is set to "Hierarchical" (the default), the child TOC is inserted into a folder that is automatically generated by the runtime of the parent HxT. The name is specified by the value of the PluginTitle attribute, as shown in the following table:
Parent TOC |
+ Child1 (id1) |
+ Child2 (id2) |
= Combined TOC |
|---|---|---|---|
+ folder1 ++ folder1.a (id1) ++ folder1.b + folder2 (id2) + folder3 |
CS1.HXT PluginStyle= "Hierarchical" + child1.a ++ child1.a.1 ++ child 1.a.2 + child1.b |
CS2.HXT PluginStyle= "Hierarchical" PluginTitle="Child2" + child2.a + child2.b + child 2.c |
+ folder1 ++ folder1.a (id1) +++ child1\CS1 ++++ child1.a +++++ child1.a.1 +++++ child1.a.2 ++++ child1.b ++ folder1.b + folder 2 (id2) ++ Child2 +++ child2.a +++ child2.b +++ child2.c + folder3 |
If the PluginTitle attribute is not present, the name of the runtime-generated folder is a concatenation of the parent namespace + a slash (\) + the child namespace.
If the value of PluginStyle is set to "Flat", the contents of the child’s HxT file are inserted directly into the node created in the parent HxT that contains the matching ID. PluginTitle is ignored, as shown in the following example.
Parent TOC |
+ Child1 (id1) |
+ Child2 (id2) |
= Combined TOC |
|---|---|---|---|
+ folder1 ++ folder1.a (id1) ++ folder1.b + folder2 (id2) + folder3 |
CS1.HXT PluginStyle="Flat" + child1.a ++ child1.a.1 ++ child 1.a.2 + child1.b |
CS2.HXT PluginStyle="Flat" PluginTitle="Child2" + child2.a + child2.b + child 2.c |
+ folder1 ++ folder1.a (id1) +++ child1.a ++++ child1.a.1 ++++ child1.a.2 +++ child1.b ++ folder1.b + folder 2 (id2) ++ child2.a ++ child2.b ++ child2.c + folder3 |