Relationship Table Links

Relationship tables enable you to link related topics to each other, across the scope of a map. In output, the Related Information links can help guide users to additional relevant information.

Default Relationship Table Overview

The first step to start using a relationship table is adding a reltable element to a map. To enable linking between the particular topics in a map, you insert the topicref elements into the appropriate relationship table cells. Heretto CCMS enables you to perform these actions by using an intuitive relationship table editor.

Figure 1. Relationship Table Operation.

The following example shows that the reltable element links the “Concept A”, “Task A”, “Reference A”, “Reference B”, and “Reference C” topics together in the “Map A”. The topics are not linked outside the map.

Reltable linking

The default relationship table layout includes three columns that correspond to the following topic types:

  • concept topic
  • task topic
  • reference topic
When you publish, these columns become link sections at the end of a topic. Each link section has a heading, for example, Related concepts, Related tasks, and Related references.
Tip: If you prefer to have only one link section, remove the Type from each column. The link section will have the heading Related Information, and contain all the links that are relevant to that topic.

By default, relationship tables handle linking in the following way:

  • Topics in a given table row link to each other
  • Topics in the same table cell don't link to each other

In the following example “Concept A” links to “Task A”, “Reference A”, “Reference B” and “Reference C” because these topics are in the same table row

Figure 2. Default Relationship Table
Default relationship table example in Heretto CCMS.

The following PDF output examples illustrate the default linking settings of a relationship table.

Figure 3. Default Relationship Table Linking (Concept A)
Relationship table linking example in the PDF output.
Figure 4. Default Relationship Table Linking (Task A)
Relationship table linking example in the PDF output.
Figure 5. Default Relationship Table Linking (References)
Relationship table linking example in the PDF output.

Customized Relationship Table Overview

Relationship tables are highly customizable. The following attributes enable you to adjust the most useful linking settings in your relationship tables.

collection-type attribute
Assigning the family value to the collection-type attribute of the relcell element enables linking between topics inserted in the same relationship table cell.

In the following example, the cell that contains the concept topics is configured to enable cell linking.

Figure 6. Cell Linking in a Relationship Table
A relationship table with cell linking enabled in Heretto CCMS.

The following PDF output example illustrates linking between “Reference A”, “Reference B”, and “Reference C” inserted in the same relationship table cell.

Figure 7. Cell Linking Example
Cell linking example in the PDF output.
linking attribute

Assigning the sourceonly value to the linking attribute of the topicref element modifies the topic linking in the following way:

  • Prevents other topics from linking to the topic

  • Enables the topic to link to other topics

Assigning the targetonly value to the linking attribute of the topicref element modifies the topic linking in the following way:

  • Enables other topics to link to the topic

  • Prevents the topic from linking to other topics

Figure 8. Sourceonly Linking in a Relationship Table
A relationship table containing a sourceonly linking topic in Heretto CCMS.

The following PDF output examples illustrate “Concept A” with linking attribute set to targetonly value.

Figure 9. Sourceonly Linking Example (Concept A)
Sourceonly linking example in the PDF output.
Figure 10. Sourceonly Linking Example (Task A)
Sourceonly linking example in the PDF output.
Figure 11. Targetonly Linking in a Relationship Table
A relationship table containing a targetonly linking topic in Heretto CCMS.

The following PDF output example illustrates “Concept A” that links to “Task A” with linking attribute set to the targetonly value. “Task A” does not link to other topics in the same relationship table row.

Figure 12. Targetonly Linking Example
Sourceonly linking example in the PDF output.

Use Cases

Consider using relationship tables if you want to reuse topics in multiple maps or reduce the number of dependencies between topics.

Figure 13. Relationship Table Links.
The following PDF output example shows that:
  • The following topics are linked together in the “Classic Toaster User Guide” map: “Cleaning the Toaster”, “Safety Warnings”, and “Specifications”.
  • The links are placed at the end of each linked topic in the “Related topic_type section.

    Where, topic_type is the type of a DITA topic that you link to.


Inserting relationship tables

Reltable links example

Reltable links example

Reltable links example

Maintenance Considerations

Keep the following considerations in mind when working with relationship tables:

  • Relationship tables require little maintenance because every link is in the reltable map element.
  • Heretto CCMS includes an editor that enables you to easily manage linking in relationship tables by dragging and dropping topics into the appropriate table columns.
  • Relationship tables do not limit topic reuse because you link topics on a map level.
  • You can add multiple relationship tables to a map. It is useful if you plan to maintain a large number of relationship table links.

Publishing Considerations

Keep the following considerations in mind when publishing maps with relationship tables:

  • Relationship table links are published at the end of a topic.
  • If you publish to a print-friendly output (for example, PDF), links may reference a page number.
  • Relationship table links resolve at publication time by populating the link text with topic titles.