Reuse Content Dialog Box

The Reuse Content dialog box provides a mechanism for reusing content fragments. DITA conref, conkeyref, and keyref attributes can be used to insert references to reusable content. The conref attribute stores a reference to another element and is processed to replace the referencing element with the referenced element. The conkeyref attribute uses keys to locate the content to reuse rather than direct references to the topic that contains the reusable content. The keyref attribute also uses keys and can be used to indirectly reference metadata that may have different values in various circumstances.

Note: For a conref or conkeyref, to reference the content inside a DITA element, the source element must have an id attribute assigned to it. The element containing the content reference acts as a placeholder for the referenced element. For more details about DITA conref and conkeyref attributes, go to http://docs.oasis-open.org/dita/v1.2/os/spec/archSpec/conref.html.
Note: For the purposes of using a keyref, keys are defined at map level and referenced afterwards. For more information about the DITA keyref attribute, go to http://docs.oasis-open.org/dita/v1.2/os/spec/common/thekeyrefattribute.html.

Oxygen XML Editor displays the referenced content of a DITA content reference if it can resolve it to a valid resource. If you use URIs instead of local paths in your XML documents and your DITA OT transformation needs an XML catalog to map the URIs to local paths, you need to add the catalog to Oxygen XML Editor. If the URIs can be resolved, the referenced content is displayed in Author mode and in the transformation output.

In Author mode, a references to reusable content (conref, conkeyref, or keyref) can easily be inserted at the cursor position by using the Reuse Content dialog box. It can be opened with any of the following methods:

Your selection at the top of the dialog box for choosing the content source determines whether Oxygen XML Editor will insert a conref, conkeyref, or keyref.

If you select Location for the content source, a content reference (conref) will be inserted. If you select Key for the content source, keys will be used to insert a content key reference (conkeyref) or a key reference (keyref).

Content Reference (conref) Options Using the Reuse Content Dialog Box

Figure: The Reuse Content Dialog Box (with the Default Insert Content Reference Options Displayed)

When Location is selected for the content source, a content reference (conref) will be inserted. Here you can specify the path of the topic that contains the content you want to reference.

The dialog box offers the following options:
Select an element from the content source Section
Show elements of type
You can use this drop-down list to select specific types of elements to be displayed in the subsequent table. This can help you narrow down the list of possible source elements that you can select.
Text Filter Field
You can also use the text filter field to narrow down the list of possible source elements to be displayed in the subsequent table.
Element Table
Present all the element IDs defined in the source topic. Use this table to select the Element ID of the element that you want to reference. You can select multiple contiguous elements to reference a block of content.
Preview Pane
Displays the content that will be references. If you select multiple elements in the element table, the content from all the selected elements is displayed.
Source Pane
Displays the source code of the element to be referenced.
Reference details Section
Reference to (conref)
Oxygen XML Editor automatically fills this text field with the value of the conref attribute to be inserted. However, you can edit this value if need be.
Reference to range end (conrefend)
If you select multiple elements (of the same type) in the element table, Oxygen XML Editor automatically fills this text field with the id value of the last element in your selection. This value will be inserted as a conrefend attribute, defining the end of the conref range.

Content Key Reference (conkeyref) Options Using the Reuse Content Dialog Box

Figure: Insert Content Key Reference Options

Choose the content source Section

When Key is selected for the content source, you can use keys to reference content. You can use the Choose Key Reference button to open the Choose Key dialog box that allows you to select one from a list of all the keys that are gathered from the root map (you can also select one from the drop-down list in the Key field).
Note: If the current DITA map is not selected as the root map, no keys will be listed.

Figure: Choose Key Dialog Box

To insert a content key reference (conkeyref), select the key that contains the content you want to reference. Notice that the file path is shown in the Href column. Keys that do not have a value in the Href column are for referencing metadata with a keyref attribute. Therefore, to insert a conkeyref, you need to select a key that has a value (file path) in the Href column. After you select a key, click OK to return to the Reuse Content dialog box.

When a key that is defined as a content key reference has been selected, the Reuse Content dialog box offers the following additional options for inserting a conkeyref:

Select an element from the content source Section
Show elements of type
You can use this drop-down list to select specific types of elements to be displayed in the subsequent table. This can help you narrow down the list of possible source elements that you can select.
Text Filter Field
You can also use the text filter field to narrow down the list of possible source elements to be displayed in the subsequent table.
Element Table
Present all the element IDs defined in the source topic. Use this table to select the Element ID of the element that you want to reference. You can select multiple contiguous elements to reference a block of content.
Preview Pane
Displays the content that will be references. If you select multiple elements in the element table, the content from all the selected elements is displayed.
Source Pane
Displays the source code of the element to be referenced.
Reference details Section
Reference type
The type of reference that will be inserted. If you selected a key that references a DITA resource, you will notice that conkeyref value is automatically selected.
Reference to
Oxygen XML Editor automatically fills this text field with the value of the conkeyref attribute to be inserted. However, you can edit this value if need be.
Fallback to (conref)
You can enable this option to define a conref attribute to be used as a fallback to determine the content reference relationship if the specified conkeyref cannot be resolved.
Reference to range end (conrefend)
If you select multiple elements (of the same type) in the element table, Oxygen XML Editor automatically fills this text field with the id value of the last element in your selection. This value will be inserted as a conrefend attribute, defining the end of the conkeyref range.

Key Reference to Metadata (keyref) Options Using the Reuse Content Dialog Box

Figure: Insert Key Reference Options

Choose the content source Section

When Key is selected for the content source, you can use keys to reference content. You can use the Choose Key Reference button to open the Choose Key dialog box that allows you to select one from a list of all the keys that are gathered from the root map (you can also select one from the drop-down list in the Key field).
Note: If the current DITA map is not selected as the root map, no keys will be listed.

Figure: Choose Key Dialog Box

To insert a key reference to metadata (keyref), select the key you want to reference.
Note: Keys that do not have a value in the Href column are for referencing metadata with a keyref attribute, whereas keys for referencing a conkeyref have a value (file path) shown in the Href column.
Note: The Description column collects data from the definition of the key, either from the navtitle element or, if missing, from the keyword element. The following example shows two key definitions that will be collected in the keys table. Their corresponding information from the Description column will display oxygen.sh and oxygen.tar.gz respectively.
<keydef keys="executableInstallLinux">
  <topicmeta>
    <keywords>
      <keyword>oxygen.sh</keyword>
    </keywords>
  </topicmeta>
</keydef>

<keydef keys="archiveInstallAll">
  <topicmeta>
    <navtitle>
      oxygen.tar.gz
    </navtitle>
  </topicmeta>
</keydef>
After you select a key, click OK to return to the Reuse Content dialog box.
When a key that references metadata has been selected, the Reuse Content dialog box offers the following additional options for inserting a keyref:
Select an element from the content source Section
This section is not used when referencing metadata.
Reference details Section
Reference type
The type of reference that will be inserted. If you selected a key that does not reference a DITA resource, you will notice that keyref value is automatically selected.
Reference to
Oxygen XML Editor automatically fills this text field with the value of the keyref attribute to be inserted.
Element name
Oxygen XML Editor automatically selects the element that is most commonly used for the selected type of key reference, but you can use the drop-down list to choose another element to use for the reference.

Finalizing Your Content Reference Configuration

Once you click Insert or Insert and close, the configured content reference is inserted into your document.
Tip: You can easily insert multiple content references by keeping the Reuse Content dialog box opened, using the Insert button.
Parent topic: Working with Content References
Previous topic: Editing DITA Content References
Next topic: Working with the Conref Push Mechanism