History | Edit

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 (or simply press Alt+Enter) 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.

Note: The element may already have an id, since in some cases Oxygen XML Editor automatically generates an ID value when the id attribute is created.

Creating a Content Reference

To create a content reference (conref), follow these steps:

  1. Make sure 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 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.
  4. 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.
  5. Select the Target ID of the element (or elements) from which you want to insert the content, and verify the content in the Preview pane. The id value of the element that you select is automatically added to the Reference to (conref) 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.

Using Copy/Paste Actions to Create a Content Reference

Oxygen XML Editor 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 Editor 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 reference (conref) using copy/paste actions, follow these steps:
  1. Copy an entire DITA element that has an ID attribute assigned to it.
  2. Place the cursor at a location where the copied element will be valid.
  3. Select the Paste as Content Reference action from the Paste Special submenu from the contextual menu.

Other Ways to Reuse Content