- This topic is empty.
-
Posts
-
-
In DITA, authors can link within topics to other topics through the <xref>, <link>, and <related-links> elements. However, there are disadvantages to hard-coding links in a topic. Hard-coded links create dependencies between topics and decrease the reusability of each topic. Since the links are hard-coded within the topic, they may not apply to other contexts in which the topic is reused. If a topic is renamed or if its path changes, the link will have to be recreated in all topics which reference this link.
Hard-coded links result in excessive maintenance.
DITA provides a powerful alternative means of linking using relationship tables. The benefit of using a relationship table is the ability to create and maintain links in one place with the map rather than in the topics. Links can be created both between topics of the same information type and between topics of different information types that are not directly related through parent/child relationships. Therefore, the best practice for linking in DITA is to use a relationship table within a map.
How do Relationship Tables Work?
Relationship tables are expressed in the CALS Table Model format using rows and columns to set up the links. Each column in a table groups similar information types together, such as concept, task, and reference. Each row in the table represents a relationship, which is generally rendered as a link, and each cell represents participants in the relationship. Therefore, when the relationship table is created, each topic reference in a cell will link to the topic references in the other cells in the same row.
For example, if we wanted to link the three topics: simpleconcept.dita, simpletask.dita, and simplereference.dita, the relationship table would look like this:
In practice, relationship tables are more complex than this simple example. When creating a more complex relationship table, it is important to remember the following:
- Each row represents a separate set of relationships and links • No relationship exists between the rows in a table
- Topic references are not needed in every cell within a row
- Each cell can contain multiple topic references
- Topic references can be repeated in multiple rows
In the complex relationship table below, each arrow represents a link which is created between the topics. Each link created in the table below will be placed at the end of each topic during production.
In a relationship table, topic references within a cell are not linked together. However, there are instances when they should be linked. Applying the collection-type attribute in the element allows you to link topic references inside a cell.
The collection-type attribute is added to give additional functionality to link-related topics. The collection-type attribute only affects the relationships within a cell—it does not affect relationships across cells. The most common collection-type value used within a relationship table is family. If you have a set of closely related concepts or tasks that need links or relationships created, other than a parent/child relationship, use the family collection-type value. For example, in the table below, the simplereference1.dita and simplereference2.dita are related using the collection-type=“family”.
You can use the linking attribute to create one-way links within a relationship table. The linking attribute values are sourceonly and targetonly. The sourceonly value creates only a link in the source topic to the target topic. The target topic will not contain a link back to the source topic. For example, the simpletask1.dita linking attribute value is set to sourceonly. Therefore, the link to simplereference1.dita and simplereference2.dita will only appear in the simpletask1.dita. The simplereference1.dita and simplereference2.dita will not contain a link back to the simpletask1.dita. These links do not affect the linking between simplereference1.dita and simplereference2.dita.
The targetonly value creates a link in the target topic to the source topic, which means that the source topic will not contain a link to the target topic.
More Complex Tables
A more complex relationship table example is shown below. In this example, the first row provides links between the three topics, concept, task, and reference. The second row provides links between the two concept topics and the reference topic. However, there is not a link created between the two concept topics. The third row creates links between all three concept topics. There are one way links created from the three concepts and one task topic to the simplereference2 topic because the reference is labeled as a ‘targetonly’ link. Therefore, links are created within the concept and task topics to the simplereference2 topic. However, there are not links in the simplereference2 topic to the other topics. There is also a one way link created between the simplereference1.dita and the task and three concept topics. The simplereference1 topic is labeled as ‘sourceonly’ so links will only be created within the simplereference1 to the other topics. The other topics will not contain a link back to the simplerefence1 topic. There are two way links created between the three concept topics and the task topic.
Row 1: Default Linking
<relrow>
<relcell>
<topicref href=“simpleconcept1.dita”/>
</relcell>
<relcell>
<topicref href=“simpletask1.dita”/>
</relcell>
<relcell>
<topicref href=“simplereference1.dita”/>
</relcell>
</relrow>Row 2: Default Linking (not all cells used)
<relrow>
<relcell>
<topicref href=“simpleconcept1.dita”/>
<topicref href=“simpleconcept2.dita”/>
</relcell>
<relcell> <!– this cell is empty on purpose –> </relcell>
<relcell>
<topicref href=“simplereference1.dita”/>
</relcell>
</relrow>Row 3: Various strategies together
<relrow>
<relcell>
<topicgroup collection-type=“family”>
<topicref href=“simpleconcept2.dita”/>
<topicref href=“simpleconcept3.dita”/>
<topicref href=“simpleconcept4.dita”/>
<topicgroup>
</relcell>
<relcell>
<topicref href=“simpletask2.dita”/>
</relcell>
<relcell>
<topicref href=“simplereference1.dita” linking=“sourceonly”/>
<topicref href=“simplereference2.dita” linking=“targetonly”/>
</relcell>
</relrow>How to Set Up the Table (Typical)
Set Up the reltable Header Row by adding the type attribute to each <relcolspec> element setting the attribute value to concept, task, and reference respectively.
<relcolspec type=“concept”/>
<relcolspec type=“task”/>
<relcolspec type=“reference”/>You can add typing in the header row as well as setting these values on the relcolspec elements for your convenience; it won’t do anything in the final produced output.
How to Set Specific Linking Behavior
Default Behavior
Insert the topicref, no additional settings
<topicref href=“simpletask1.dita”/>
Source or Target Only
Add the linking attribute to the <topicref> element setting the value to sourceonly or targetonly.
<topicref href=“simpletask1.dita” linking=“sourceonly”>
Family Collection
Add a <topicgroup> inside the cell and in the collection-type attribute set the value to family; Then insert the topics you want.
<topicgroup collection-type=“family”>
<topicref href=“simpletask1.dita”/> …
</topicgroup>Four Column Example
You can change how the table is constructed if it makes it easier for you to conceptualize the relationships:
-
- You must be logged in to reply to this topic.