DITA Content Reference
A DITA content reference, or conref, is one of the main content reuse features of DITA. It is a
mechanism for re-using the same content in multiple topics (or even in multiple locations
within the same topic).
For a conref to be created, the source content must have an
id attribute that the conref can reference. Therefore,
creating a conref requires that you add an id to the
content to be reused before inserting a conref into the topic that reuses
the referenced content.
Assigning an ID to the Referenced Content
To add an id to a DITA element in a topic, place the cursor on the element
and select 
Edit
Attributes from the contextual menu to open the in-place
attribute editor. Enter id as the
Name of the attribute and a value of your choice in the
Value field. You can also use the
Attributes view to enter a value in the
id attribute.
id, since in some cases, Oxygen XML Author Eclipse plugin automatically generates an ID value when the id
attribute is created. Creating a Content Reference
To create a content reference (conref), follow these steps:
- Make sure 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 the
Reuse
Content action on the main toolbar (or from the DITA
menu or Reuse submenu of the contextual menu). The Reuse
Content dialog box is displayed. - In the Location field of the Reuse Content dialog box, select the topic that contains the element you want to reference. The elements that you can reference are presented in a table.
- Select the Target ID of the element (or elements) to have their content inserted, and verify the content in the Preview
pane. The
idvalue of the element that you select is automatically added to the Reference to (conref) 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.
Using Copy/Paste Actions to Create a Content Reference
Oxygen XML Author Eclipse plugin also includes support for creating content references with simple copy/paste actions. The copied content must be an entire DITA XML element with an ID attribute. 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.
conref) using copy/paste actions, follow
these steps:- 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 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 references.
- An alternate way to reuse content is to use the Oxygen XML Author Eclipse plugin Create Reusable Component and Insert Reusable Component actions (available in the DITA menu and the Reuse submenu of the contextual menu). They handle the details of creating an ID and conref and create reusable component files, separate from your normal content files. This can help you manage your reusable content more effectively.
- You can also insert reusable content using content key references. This may also make reusable content easier to manage, depending on your particular situation and needs.
- 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.