Edit online

Creating a DITA Content Key Reference

DITA Content Key Reference

A DITA content key reference, or @conkeyref, is a mechanism for inserting a piece of content from one topic into another. It is a version of the DITA content reference mechanism that uses keys to locate the content to reuse rather than direct references to topics that contain reused content.

As with a conref, a conkeyref requires that the element to be reused has an @id attribute. It also requires the topic that contains the reusable content to be assigned a key in a map. As with all uses of keys, you can substitute multiple maps or use profiling to create multiple definitions of keys in a single map. This allows the same @conkeyref to pull in content from various sources, depending on how your build is configured. This can make it easier to create and manage sophisticated content reuse scenarios.

Creating a Content Key Reference

To create a content key reference (@conkeyref), follow these steps:

  1. Make sure the topic that contains the reusable content is assigned a key in the DITA map and the element you want to reference has an ID assigned to it.
  2. In Author mode, place the cursor at the location where you want the reused content to be inserted.
  3. Select Reuse Content on the main toolbar (or from the DITA menu or Reuse submenu of the contextual menu). The Reuse Content dialog box is displayed.
  4. Select the Key radio button for the content source and use the Choose Key Reference button to select the key for the topic that contains the reusable content (you can also select one from the drop-down list in the Key field). The elements that you can reference from the source are presented in the table in the middle of the Reuse Content dialog box.
  5. Select the Target ID of the element (or elements) that you want to insert, and verify the content in the Preview pane. The @id value of the element that you select is automatically added to the Reference to (conkeyref) field.
  6. Make any other selections you need in the Reuse Content dialog box. If you select multiple elements, the Expand to (conrefend) field is automatically filled with the @id value of the last element in your selection.
  7. Click Insert or Insert and close to create the content reference.
Note: If you are using Text mode, when you insert a @conkeyref attribute, after you enter the first quote (conkeyref="), the Content Completion Assistant will list all the defined keys that you can select from. Also, after you select the key, the Content Completion Assistant will then list the element IDs from the referenced topic, allowing you to insert an anchor. Note that this only works for local files.

Using Copy/Paste Actions to Create a Content Key Reference

Oxygen XML Author also includes support for creating content key references with simple copy/paste actions. When the DITA content is processed, the key references are resolved using key definitions from DITA maps. The copied content must be an entire DITA XML element with an ID attribute and the topic that contains the reusable content must have a key assigned in a DITA map. Also, the location in the document where you paste the element must be valid, although as long as the Smart paste and drag and drop option is selected in the Schema-Aware preferences page, if you try to paste it in an invalid location, Oxygen XML Author will attempt to place it in a valid location, and may prompt you with one or more choices for where to place it.

To create a content key reference (@conkeyref) using copy/paste actions, follow these steps:
  1. In the DITA Maps Manager view, make sure that the Context combo box points to the correct map that stores the keys.
  2. Make sure the topic that contains the content you want to reference has a key assigned to it. To assign a key, right-click the topic with its parent map opened in the DITA Maps Manager, select Edit Properties, and enter a value in the Keys field.
  3. In a topic with an assigned key, copy an entire DITA element that has an ID attribute assigned to it.
  4. Place the cursor at a location where the copied element will be valid.
  5. Select the Paste as Content Key Reference action from the Paste Special submenu from the contextual menu.

Other Ways to Reuse Content