Key References
You can indirectly link to topics in a map by using key references. You can consider key references as a reuse-friendly alternative to Peer Cross-References.
Overview
Instead of directly linking to a topic by using the exact file path, key references link to a key name assigned to a topic in map. In different maps, topics with key references can link to different topics without limiting topic reuse.
The following example shows that:
- “Topic A” and “Topic C” are reused in “Map A” and “Map B”.
- “Topic C” contains a key reference that links to the “sample_key” key
- In “Map A”, “Topic C” links to “Topic B” because it has the “sample_key” value assigned
- In “Map B”, “Topic C” links to “Topic D” because it has the “sample_key” value assigned
Use Cases
Consider using key references in the following scenarios:
- When you want to reuse a topic in different maps and want to make the reused topic link to different topics.
Maintenance Guidelines
Keep the following guidelines in mind when using key references:
- The following Heretto CCMS reports can help you manage key references:
- Invalid Keyrefs Report checks for broken key references. This report lists keyrefs linking to key names that are not defined in the map.
- Folder Keys Report identifies all the keys used in a specific folder and where they're used. This report is helpful if you're looking for ways to maximize your reuse opportunities.
- Develop a key naming convention that is easy to implement and use.
- Over a given map, we recommend using unique key values.
Publishing Guidelines
Keep the following guidelines in mind when publishing content with key references:
- Your map won't publish if the key references in the map are not resolved.
- If there are the same key values in a map, the key resolves to the first instance of that key name in the map.
- If you publish to a print-friendly output (for example, PDF), links may reference a page number.
Assign Key Names
You must set a key name on a topicref element in a map to indirectly link to a topic.
- In the content library, right-click a map and select Dock button.
- In the Map Editor, hover over the topic you want to assign a key name to.
- Click the Key icon.
- In the Keys field, enter a key name and click Update.
Insert Key References
Create an indirect, inline link by inserting a key reference to a key name.
In a map, assign a key name to the topicref element that you want to indirectly link to. See Assign Key Names.