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:
- 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.
- In Author mode, place the cursor at the location where you want the reused content to be inserted.
- 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. - 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. - Select the Target ID of the element (or elements) that you want
to insert, and verify the content in the Preview pane. The
@idvalue of the element that you select is automatically added to the Reference to (conkeyref) field. - 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
@idvalue of the last element in your selection. - Click Insert or Insert and close to create the content reference.
@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 Eclipse plugin 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 Eclipse plugin will attempt to place it in a valid location, and may prompt you with one or more choices for where to place it.
@conkeyref) using copy/paste actions,
follow these steps:- In the DITA Maps Manager view, make sure that the Context combo box points to the correct map that stores the keys.
- 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.
- In a topic with an assigned key, copy an entire DITA element that has an ID attribute assigned to it.
- Place the cursor at a location where the copied element will be valid.
- Select the Paste as Content Key Reference action from the
Paste Special
submenu from the contextual menu.
Other Ways to Reuse Content
- You can use the Components tab in the DITA Reusable Components view to easily insert content key references.
- You can also insert reusable content using content references (conref).
- Other topics in this section include information about more specialized or advanced ways or reusing content, such as code references, the conref push mechanism, variable text, key scopes, and branch filtering.