DITA relationship tables

Understand the concepts of related topics in a structured document, how is a relationship table used to create links for the related topics in FrameMaker.

In a set of DITA topics, you often have topics that are related to each other. In this case, you might want to include a set of related (see also) links at the end of each topic. This provides your readers with further reading reference, if required.

For example, if you are covering the Save As options in FrameMaker as separate topics:

Save As
Save As PDF
Save As Review PDF
Save As XML

In this case, at the end of each of these topics, you might include related links to the other three topics.

Using DITA maps

Relationship tables in FrameMaker allow you to create related links in DITA topics. You use relationship tables in DITA maps. This implies that you need to create a DITA map and then include the topics in your topic set in the DITA map. You then add relationship tables to the map. In the relationship tables you define the related topics contained in the DITA map.

DITA types to add

You can add the following DITA topic types to a relationship table:

Topic
Task
Concept
Reference

Adding related topics to a relationship table row

To specify that two or more topics in a DITA map are related, you need to add these to a single row in a relationship table. For the steps to create a relationship table, see Create a relationship table.

For example, to specify that the topics Save As, Save As PDF, Save As Review PDF, and Save As XML are related topics:

Relationship table in Document view

Note: A relationship table in FrameMaker, when viewed in the Document view has the same appearance as a FrameMaker table that you include as part of your content.

You can add any number of rows to a relationship table. FrameMaker treats all topics in a row as related.

You can add any number of relationship tables to a DITA map. You might do this to group together sets of related topics.

Specifying the order of related topics in a relationship table row

The order of the related topics in a table row defines the sequence in which the topics display in the Related Links section of the DITA map output.

In the following example, the Related Links section of the Save As PDF topic will display as:

Save As
Save As Review PDF
Save As XML

Relationship table in Document view

This implies that if you change the order of the topics in the table, the sequence in the Related Links section will display differently.

Create a relationship table

Learn how to create a relationship table in FrameMaker, see a sample relationship table workflow.

In the Structure View of a DITA map, place the insert point at end of the topic and at the same level as the topicref elements.
To display the Smart Catalog, press Ctrl + 1 and choose reltable.

The Insert Table dialog is displayed.
Specify the number of columns and rows.

The number of columns depends on the number of related topics that you plan to group together.

The number of rows depends on the number of groups of related topics that you plan to create.

Note: You can also choose to create multiple relationship tables for multiple groups of related topics.
Click Insert.

A relationship table is added to the DITA map.
To display the relationship table in a tabular view, go to the Document view.

While you can add topics to a relationship table from the Structure View, the tabular view provides a more convenient mode to work with.

Default relationship table (with 4 columns and 1 body row)

In each cell of the relationship table header, you specify the DITA topic type of the related topics that you plan to include in body cells of the column.

FrameMaker allows you to add the following DITA topic types to a relationship table:
- Topic
- Task
- Concept
- Reference
Note: By default, FrameMaker supports the Topic type. So if you plan to only include topic types in the table, you do not need to set the type attribute.
To add a specific DITA topic type to a column in the table:
1. Place the insertion pointer in the table header cell.
2. Open the Attributes dialog (Element > Edit Attributes).
3. Set the @type attribute to the DITA topic type:
  
  Topic type - attribute value: topic
  
  Task type - attribute value: task
  
  Concept type - attribute value: concept
  
  Reference type - attribute value: reference
  
  Important: The attribute values are case-sensitive.
  
  If you set type attribute as described above, the column title is updated:
  
  Updated type attributes
In each cell of a row in the relationship table, you add a topic reference of the related topics. This implies that, one set of related topics need to be included in the cells of one row of the table.

To add topic references of related topics in the table body cells:
1. Place the insertion point in the a cell of a row, in the Elements catalog (Element > Element Catalog), double-click the topicref element to add it to the cell.
  
  The Insert Element dialog is displayed.
  
  You can also use the Smart Catalog to insert the topicref element.
  
  Press Ctrl+1 to display the Smart Catalog. Select and add the topicref element.
2. In the HRef field, enter the path to a topic file and click OK.
  
  Alternatively, use the Browse button to navigate to and select the topic.
  
  The topic reference is added to the table row.
  
  Tip: If you are unable to add a topic reference to a table cell, check the topic type specified in the column header.
3. Add one topic reference (to a related topic) to each cell of the table row.

If the table included multiple rows, you can add multiple groups of related topics (references) to each row.

Sample relationship table workflow

To test the output after Create a relationship table in a DITA map, you can use the Save As PDF option in FrameMaker.

Ensure that the DITA map is selected.
Choose File > Save As PDF.
In the PDF Setup dialog, click Set.

The PDF output of the DITA map displays the Related Links sections for the topics that you include in the cells of the relationship tables in the DITA map.

Important: The PDF Save As functionality is used in this section as an example. You can also publish the DITA map to the output formats available in FrameMaker’s Multi-Channel publishing feature.

The topics display in the same order as which you specify them in the cells of the table row.

Also, related topics that display do not include the current topic. In the sample relationship table described below:

Relationship table in Document view

The Save As topic Related Links section displays:

Save As PDF
Save As Review PDF
Save As XML

It does not display the Save As (current) topic.