Insert content using a conkeyref

When you want to reference re-useable content many times, you can use a content key reference. In this case the referenced content is linked in one place in the associated map, which makes it easier to update than a conref that uses a file name each time you insert a reference. Inserting content using a key is similar to inserting a content reference by a file.

Tips and tricks

  • To insert a link to the copy of the referenced content which forces readers to open that topic, follow the steps in Insert a key reference as a link.
  • You must set the root DITA map for the component to access reusable keys you've defined in the map. If you don't, when you add a content key reference you'll only get a content reference.
  • You must also have your content keys defined in the root or a sub map before inserting a reference to that key. If you haven't defined keys yet, follow the steps in Assign a key to a topic in Oxygen.
  • Rules that apply to conrefs also apply to conkeyrefs:
    • The referencing element must be the same type (element name) as the referenced element. For example, inserting an unordered list referenced by a key into a paragraph where unordered lists can be inserted.
    • The referencing element must be valid. For example, an unordered list <ul> element must contain at least one <li> element.

Insert a key reference in Oxygen:
  1. In Inspire, go to Components.
  2. Navigate to the DITA topic where you want to insert a key reference.
  3. Right-click the topic and select Edit...
  4. In the toolbar, click Show DITA Map tool.
    In the left pane, make sure that you see the map with the defined key.
    If you don't, select a root map, save and submit the topic, and re-open it.
    Repeat step 3 to make sure the map association is saved.
  5. Place your cursor where you want to insert the key content reference.
    Remember that where you insert a reference, you must be the able to insert the same type (element name) as the referenced element.
  6. From the toolbar, click the link icon and then select Content Reference.
    You can also right-click in the place where you want to insert the key content reference, select Reuse, and then select Content Reference...
  7. On the Select Component screen, select the file that contains the re-useable content, and then click Select.
  8. On the Content Reference screen, scroll through the topic to find the content that you created a key definition for.
  9. On the Content Reference screen, click OK.
    Results:
    • In the left Outline pane, you see the reference content you inserted.

    • In the center Editing pane, you see the reference content you inserted as a read-only copy. To edit the inserted text, click .

    • In the right Attributes pane, you see the type of link used to reference the content. It should be conkeyref.

  10. In the toolbar, click Save and Submit.
    Troubleshooting:
    If you make changes to links and references, you can ensure the most up-to-date information is being displayed by following these steps:
    1. Go to the toolbar.
    2. Click the Refresh references icon .

      Whenever you refresh references, Inspire automatically:

      • Saves the changes locally
      • Submits the changes to the database
      • Reloads the content in the editor

    What happens if I delete the text that's referenced in another component?

    After creating a reference to another component, Inspire tracks the relationship.

    • If the following statements are both true:
      • An administrator has enabled an optional feature to help you manage referenced content
      • Changes are made in the referenced component that impacts the reference
    • The user is warned that this referenced component will be updated also.
    • For more information, read Save changes in referenced components.