Edit online

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 https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/conref.html.
Note: For the purposes of using a @keyref, keys are defined at map level and referenced afterward. For more information about the DITA @keyref attribute, go to https://www.oxygenxml.com/dita/1.3/specs/langRef/attributes/thekeyrefattribute.html.

Oxygen XML Author 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 in Oxygen XML Author. If the URIs can be resolved, the referenced content is displayed in Author mode and in the transformation output.

In Author mode, a reference 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:
  • Click the Reuse Content action on the main toolbar.
  • In the contextual menu of the editing area, go to Reuse > Reuse Content.
  • Go to DITA > Reuse Content.

Your selection at the top of the dialog box for choosing the content source determines whether Oxygen XML Author 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 1. Reuse Content Dialog Box (with the Default Insert Content Reference Options Displayed)

Choose the content source Section

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
Presents all the element IDs defined in the source topic. Use this table to select the Target 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 Author 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 Author 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 2. 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.
Tip: You can also use the DITA Reusable Components view for similar purposes.
Figure 3. Choose Key Dialog Box
The Choose Key dialog box includes the following:
  • Change Root Map - Opens a small dialog box that allows you to select a root map.
  • Search Filter - You can enter text in the filter field at the top of the dialog box to filter the list and search for a specific key.
  • Sortable Columns - The dialog box includes the following columns that can be sorted by clicking on the heading:
    • Key - The name of the key (the value of the @keys attribute).
    • Description - The description of the key that is obtained from its definition. Keys that are defined with a text value in the <navtitle> or <keyword> element have that value listed in this column.
    • Href - Keys that are defined with a value in an href attribute have that href value listed in this column.
    • Definition Location - The name of the DITA map where the key is defined.
  • Group by Definition Location - A contextual menu action that can be used to group (and sort) all the keys based upon the value in the Definition Location column.

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 does have 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
Presents all the element IDs defined in the source topic. Use this table to select the Target 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 Author 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 select 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 Author 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 4. 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.
Tip: You can also use the DITA Reusable Components view for similar purposes.
Figure 5. Choose Key Dialog Box
The Choose Key dialog box includes the following:
  • Change Root Map - Opens a small dialog box that allows you to select a root map.
  • Search Filter - You can enter text in the filter field at the top of the dialog box to filter the list and search for a specific key.
  • Sortable Columns - The dialog box includes the following columns that can be sorted by clicking on the heading:
    • Key - The name of the key (the value of the @keys attribute).
    • Description - The description of the key that is obtained from its definition. Keys that are defined with a text value in the <navtitle> or <keyword> element have that value listed in this column.
    • Href - Keys that are defined with a value in an href attribute have that href value listed in this column.
    • Definition Location - The name of the DITA map where the key is defined.
  • Group by Definition Location - A contextual menu action that can be used to group (and sort) all the keys based upon the value in the Definition Location column.

To insert a key reference to metadata (@keyref), select the key you want to reference. Keys that do not have a value in the Href column are for referencing metadata with a @keyref attribute. Therefore, to insert a @keyref, you need to select a key that does not have 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 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 Author automatically fills this text field with the value of the @keyref attribute to be inserted.
Element name
Oxygen XML Author 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.