Collection types
The collection-type attribute of the topicref element defines the relationship between any nested topic references within a ditamap. Changing the collection type affects the way in which automatic links and topic previews are generated when the ditamap is processed to an output format.
The way links are generated during output processing is dependent upon the collection-type attribute of parent topicref elements in the hierarchy section of the ditamap, or the containing relcell section in the reltable section of the ditamap. (A parent topicref is one containing nested topicref elements, or child nodes.) The collection-type therefore defines the type of hierarchical relationship between members of the same branch of a ditamap tree, or in the same cell in the relationship table relcell element.
- unordered
- A collection of topics where links are generated from parent to children, and from children to parent.
- family
- A collection of topics where links are generated from parent to children, from children to parent, and from sibling to sibling.
- sequence
- A collection of topics where links are generated from parent to children, from children to parent, and from child to previous sibling (if applicable) and next sibling (if applicable).
- choice
- Not commonly used, but is intended for situations where the reader needs to select one child topic to proceed. This might be useful when the output document is an interactive decision-support application. Most processors treat choice in the same way as unordered.
- tree
- Tree is not supported.
Example syntax:
<topicref href="abc.dita" collection-type="sequence"
/>
Although collection-type attributes are valid in relationship table relcell elements, some don't make a lot of sense in that context.
For example, setting a collection-type in a relationship table cell to sequence will result in a Next Topic link in the output linking to the next topic referenced in the cell, rather than the next topic in the TOC sequence (as may logically be expected by the reader).
Although it is possible to set a collection-type attribute of sequence to a relcell element, this is generally confusing to the user, as it will set a topic sequence that differs from the sequence of topics in the hierarchy. The same logic applies to the choice attribute value. For this reason, avoid using collection-type attribute values of sequence and choice. An exception is when you are creating documents with multiple sequential navigation pathways.
Likewise, a reltable doesn't often have parent/child relationships like the hierarchy section of the map does, so using a family collection-type again rarely makes sense in reltables.