Block Links

Relationship Table Links

Relationship tables enable you to link related topics in a map.

Default Relationship Table Overview

You begin a relationship table by 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. easyDITA enables you to perform these actions by using an intuitive graphical interface.

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.

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

  • concept topic
  • task topic
  • reference 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. The reference topics link to “Concept A” and “Task A” but don't link to each other because they are in the same relationship table cell.

Figure 2. Default Relationship Table
Default relationship table example in easyDITA.

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 easyDITA.

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

  • Allows 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:

  • Allows other topics to link to the topic

  • Prevents the topic from linking to other topics

In the following example, “Concept A” links to other topics in the same relationship table row but other topics don't link to “Concept A”.

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

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.

In the following example, “Task A” doesn't link to other topics in the same relationship table row but other topics link to “Task A”.

Figure 11. Targetonly Linking in a Relationship Table
A relationship table containing a targetonly linking topic in easyDITA.

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: “Safety Warnings”, “Cleaning the Toaster”, 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.









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.
  • easyDITA 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 in the “Related Links” section.
  • If you publish to a print-friendly output (for example, PDF), links may reference a page number.
  • Relationship table links resolve at publish by populating the link text with topic titles.

Insert a Relationship Table

Inserting a reltable element into your map enables you to create links between topics without the need to edit the individual topics.

  1. In the content library, hover over a map and click the Dock button.
  2. In the map editor pane , right-click the map title and select Append Element > Empty > reltable .
Add topics to the relationship table and customize linking options. See Link Topics in a Relationship Table .

Link Topics in a Relationship Table

You create links by dragging and dropping the topics from the map editor to the appropriate relationship table cells.

Note: A default relationship table links topics in the following way:

  • Topics in the same relationship table row link to each other

  • Topics in the same relationship table cell don't link to each other

Insert a blank relationship table into your map. See Insert a Relationship Table.
  1. In the content library, hover over a map and click the Dock button.
  2. In the map editor pane, at the bottom of the map, click the reltable element.
    The relationship table editor pane opens.
  3. From the map editor pane, drag and drop the topics that you want to link to the appropriate relationship table columns.
    Drag and drop a concept topic to the concept column.
  4. If you want to link another group of topics, click the Add a Row button and repeat 3.
If needed, customize linking in your relationship table. See Customize Linking in a Relationship Table.

Customize Linking in a Relationship Table

You can customize your relationship table linking settings by modifying specific attributes.

Link topics in a relationship table. See Link Topics in a Relationship Table.
  • If you want to enable linking between topics in the same cell, do the following:
    1. In the map editor pane, right-click the appropriate relcell element and select Edit element attributes .
    2. From the collection-type drop-down menu, select family .
    3. Click Save .
  • If you want to prevent a topic from linking to other topics, do the following:
    1. In the Relationship Table Editor pane, right-click the linked topic and select Edit Properties .
    2. From the linking drop-down menu, select targetonly .
    3. Click Save .
  • If you want to prevent other topics from linking to the topic, do the following:
    1. In the Relationship Table Editor pane, right-click the linked topic and select Edit Properties .
    2. From the linking drop-down menu, select sourceonly .
    3. Click Save.

Related Links

The related-links element enables you to quickly add links to related information at the end of a topic.

Overview

By default the related-links element inserts at the end of the topic.

The following example shows that:
  • “link A” links to “Topic B” in the content library.
  • “link B” links to a non-DITA document in the content library.
  • “link C” links to a website.
  • “link D” links to a document hosted on an external server.
    Important: Always ensure that the files that you link to are not malevolent. Be extra cautious when linking to executables like EXE or APP files.
Figure 14. Related Links Operation

Use Cases

Consider using the related-links element in the following situations:

  • When you want to link to DITA or non-DITA files in the content library that are not included in the map.
    Tip: When you want to link to a DITA file that is in the same map, we recommend using the Relationship Table Links because they do not limit topic reuse.
  • When you want to link to external resources like websites or documents on external servers.
Figure 15. Related Links.
The following example from the Jorsek Portal shows that:
  • “Reference A” links to a DITA topic in the content library.
  • “Sample_Word_Document.docx” links to a Microsoft Word document in the content library. When you click it, the file downloads.
  • “DITA Open Toolkit Homepage” links to https://dita-ot.org/. The link has custom link text, and a description that is visible as a tooltip when you hover over the link.

Maintenance Guidelines

The related-links element require a moderate level of maintenance because they may limit topic reuse. If you do not want to limit topic reuse, consider using Relationship Table Links or Map Links.

Keep the following guidelines in mind when using related-links elements.
  • If you link to a DITA topic, the title element of the topic is used as the link text. To reduce maintenance, we do not recommend entering custom link text.
  • Do not link to DITA maps as this may cause unexpected results in some outputs.
  • If you link to a non-DITA resource in the content library, the file name is used as the link text. If needed, enter custom generic link text.
  • easyDITA prevents you from removing resources that are linked in other topics. When you attempt to move a resource to Trash, a warning appears. You need to remove the references to the resource before moving it to Trash.
  • If you link to external resources, for example websites, you must add a link text manually. Remember to make it generic to avoid maintenance issues.

Publishing Guidelines

Keep the following guidelines in mind when publishing content with related-links elements:

  • Because the related-links element gathers links in one element at the end of a topic you can easily apply conditional profiling to this element or links inside it so that links are included, for example, only in online outputs.

    For more information, see Conditional Processing Strategies.

  • We do not recommend linking to elements in other topics because some publishing engines or publishing scenarios may produce unexpected results in the output.
  • If you publish to a print-friendly output (for example, PDF), links may reference a page number.
  • The related links are usually displayed at the end of the topic. Some web-like outputs (for example, webhelps) may display them in a separate navigation pane.
  • If you publish to a print-friendly output (for example, PDF), ensure that the topic that you link to is included in the same map as the topic that you link from.
  • If you publish to a web output (for example, webhelps, or Jorsek Portal), you can link to topics not included in the same map as the topic that you link from.

Insert Related Links

The related-links element inserts at the end of a topic.

  1. In the content library hover over a map or a topic and click the Open button.
  2. With your cursor anywhere in the topic, insert a related-links element.
    Figure 16. Empty Related-Links Element.

    The related-links element inserts as the last element in a topic.

  3. Optional: In the related-links element, do any of the following:
    • To create containers for author-arranged groups of links, insert linklist elements.
      Tip: It is useful if you insert several related links and want to divide them into meaningful categories. Each of the linklist element can contain an introductory title element.
    • To create containers for a groups of links with common characteristics like audience, insert linkpool elements.
      Tip: You can profile linklist elements for different audiences. Each of the linkpool element can contain an introductory title element.
  4. Insert a link by doing the following:
    1. In the related-links element, linkpool element, or linklist element, insert a link element.
      Figure 17. Empty Link Element
    2. Click Link Empty and from the context menu, select Change.
      Figure 18. Link Element Context Menu
    3. In the dialog, from the Link To drop-down menu select a link type.
    4. Select file or fill in the Href field.
    5. Click Apply.
    6. If needed, repeat 4.
  5. Optional: In the link element. customize the links by doing any of the following:
    • To provide custom link text, insert and fill in the linktext element.
    • To provide a link description, insert and fill in the desc element.
    Figure 19. Custom Link Text and Link Description.

    The following example shows a link to https://dita-ot.org with custom link text and a link description.

Test-publish the resource and verify that the linking works as expected in the output.
Figure 20. Related Links.
The following example from the Jorsek Portal shows that:
  • “Reference A” links to a DITA topic in the content library.
  • “Sample_Word_Document.docx” links to a Microsoft Word document in the content library. When you click it, the file downloads.
  • “DITA Open Toolkit Homepage” links to https://dita-ot.org/. The link has custom link text, and a description that is visible as a tooltip when you hover over the link.

Map Links

Map links enable you to link topics in a map based on their parent-children relationship in the map structure.

Overview

You create map links by using the appropriate map structure and the collection-type attribute.

The collection-type attribute can take the following values:

sequence value
Generates an ordered list of links from parent to children. The order of links is the same as the order of topics in the map.
unordered value
Generates an unordered list of links from parent to children. The order of links is the same as the order of topics in the map.
family value
Generates an unordered list of links from parent to children and from sibling to sibling. The order of links is the same as the order of topics in the map.
choice value
Uncommon and typically used in custom outputs that enable the user to select one child topic to continue. In most cases, it is rendered in the same way as the unordered value.
Figure 21. Map Links Operation.
The following example shows that:
  • The “Task B” is a process topic with the collection-type attribute set to the sequence value.
  • “Task B” will link to “Task C”. “Task D”, and “Task E” in the output.
  • The linked topics will not link to each other outside the map.

Use Cases

Consider using map links in the following situations:

  • When you want to create a process topic based on map links
    Figure 22. Process Map Structure.
    The following example shows that:
    • There are three procedures appended under the “Process A” topic.
    • The “Process A” topic has the collection type attribute assigned
    Figure 23. Rendered Process Topic.

    The following PDF example shows a sample process of the structure visible in Process Map Structure.

  • When you want to enhance navigation between certain sections in a web format like webhelp

Maintenance Considerations

Keep the following considerations in mind when working with map links:

  • Map links do not limit topic reuse because you link topics on a map level.
  • Map links are based on map structure. If you change the map structure, they links will be updated.

Publishing Considerations

Keep the following considerations in mind when publishing map links:

  • Map links resolve at publish and link text is populated with the topic titles.
  • If you publish to a print-friendly output (for example, PDF), links may reference a page number.
  • You must use the DITA Open Toolkit and set the args.rellinks parameter to all.

Configure Map Linking

You configure map linking by assigning the appropriate collection-type attribute values.

  1. In the content library, hover over a map and click the Open button.
  2. Set the collection-type attribute of the parent topic by doing the following:
    1. In the topic editor, in the pane on the left, right-click the parent topic and select Edit element attributes.
      Figure 24. Parent Topic Example.

      The following example shows that the “Process A” topic is a parent of the “Procedure A”, “Procedure B”, and “Procedure C” topics.

    2. In the Edit Properties window, from the collection-type drop-down list, select a value.
      Note: The collection-type attribute can take the following values:
      sequence value
      Generates an ordered list of links from parent to children. The order of links is the same as the order of topics in the map.
      unordered value
      Generates an unordered list of links from parent to children. The order of links is the same as the order of topics in the map.
      family value
      Generates an unordered list of links from parent to children and from sibling to sibling. The order of links is the same as the order of topics in the map.
      choice value
      Uncommon value used in custom outputs that enables the user to select one child topic to continue. In most cases, it is rendered in the same way as the unordered value.
    3. Click Save.
Test-publish the resource and verify that the linking works as expected in the output.
Important: Linking created by adjusting the collection-type attribute is compatible only with the DITA Open Toolkit publishing scenarios with the args.rellinks parameter set to all.
Figure 25. Rendered Process Topic.
The following PDF example shows that:
  • The “Process A” topic is a parent of the “Procedure A”, “Procedure B”, and “Procedure C” topics.
  • The “Process A” topic has the collection-type attribute set to the sequence value.