Table of Contents
User Guide
Key References
Key References
Key references (keyrefs) are a form of indirect inline links that use key names defined in a map to link to resources. This type of indirect linking allows for topics to be reused in multiple publications.
Assigning a Key Name to Topics
Set the key name on a topic so you can indirectly link to it from a topic.
Inserting a Keyref
Insert a keyref to a key name defined in the map and create an indirect, inline link to an element in a map.
Key References

Key references (keyrefs) are a form of indirect inline links that use key names defined in a map to link to resources. This type of indirect linking allows for topics to be reused in multiple publications.

You can think of key references as links to ‘things’ (key names) in a map rather than specific topics. And because you’re linking to ‘things’ and not specific topics, this makes linking more abstract and optimizes your reuse capabilities.

section
Let’s look at this another way. In your phone’s contact list, you probably don’t save your contacts based on their phone number and use their name instead. And any time that you want to call someone, you probably don’t search for the exact phone number. Instead you search for the contact’s name. Key references operate along these lines.
With key references, instead of linking to topics using the exact filename, you link to the key name assigned to it. This way, if the topic changes, you can easily associate the key name to another topic. Continuing with the phone example, if your contact’s number changes, you can just associate the contact name to a new number. And if the topic being referenced changes, just assign the key name to the new topic. This also allows you to reuse topics in multiple publication maps.
To create a key reference, you need to do the following:
section

Keyref Example

You need to publish a manual for both the Toaster 1000 and Toaster 1500. Both publication maps reuse the Setting up the Toaster topic. However, they contain different Button Functions topics.
Although the content in the Button Functions topics is different, conceptually they’re the same. So, within each publication map, you’ll use the same key name for the Button Functions topics, which is buttonFunctions.
In the Setting up the Toaster topic, which is reused in both publications, there is a keyref indirectly linking to the key name buttonFunctions:
Depending on the publication map used, the link in the Setting up the Toaster topic will resolve to the corresponding Button Functions topic included in the map. Let’s look at the Toaster 1000 publication map:
When the Setting up the Toaster topic is in the Toaster 1000 map, the keyref to buttonFunctions will link to the Toaster 1000 Button Functions topic and display like this:
But when the Setting up the Toaster topic is in the Toaster 1500 map, the keyref to buttonFunctions will link to the Toaster 1500 Button Functions topic instead:
This enables you to reuse the Setting Up the Toaster topic in both publication maps. Then depending on the map context, the keyref resolves to display the corresponding topic the key name is assigned to in each map.
Assigning a Key Name to Topics

Set the key name on a topic so you can indirectly link to it from a topic.
  1. Open a map in the Map Editor.
  2. In the Map Editor, hover over the topic you want to assign a key name to.

    Expected Result
    A quick list of icons display.

  3. Select the key icon.

    Expected Result
    The Keys field displays.
  4. Enter a key name for the topic.

    Example
  5. Click Update.
  6. Click Save to save the changes you made to the map.
result

A key name is defined for the selected map element. This key name can be used when inserting a keyref in a topic. For more information, see Inserting a Keyref.

Inserting a Keyref

Insert a keyref to a key name defined in the map and create an indirect, inline link to an element in a map.

prereq
You must assign a key name to the topic that you want to indirectly link to before inserting a keyref. For more information, see Assigning a Key Name to Topics.
Remember:When using keys, you must have a map open or map context set in order to see available keys and for keyrefs to resolve.
  1. Open a topic in the Topic Editor.
  2. Place your cursor where you want to insert a keyref.
  3. Click Link -> Keyref .Keyref drop-down menu
  4. Enter or select the key name you want to create a keyref to.

    Example
result

A key reference is inserted in the topic, which indirectly links to the topic in the map with the key name.