History | Edit

Cross Reference (xref) Dialog Box

The Cross Reference (xref) dialog box is displayed when you insert a Cross Reference or Related Link to Topic (from the Link drop-down menu). It allows you to insert a link to a target resource at the current location within a document (for a Cross Reference link) or in a related links section (for a Related Link to Topic). The target resource can be the location of a file or a key that is already defined in your DITA map structure. Once the target resource has been selected, you can also target specific elements within that resource.

Figure: Cross Reference (xref) Dialog Box

This dialog box includes the following sections and fields:
Choose the Target Resource Section
Location
If you select Location for the target, the link is expressed in an href attribute.
Key
If you select Key for the target, keys will be used to express the link in a keyref attribute. 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).
Tip: You can also use the DITA Reusable Components view for similar purposes.

Figure: 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 keys.
  • Sortable Columns - The dialog box includes the following columns that can be sorted by clicking on the heading:
    • Key - The name of the key.
    • Description - The description of the key that is obtained from the definition of the key (for example, the description for a keydef would be found in the keyword element inside topicmeta, or the description for a topicref would be found in a navitle element). For more information about where the data in this column is collected, see this note.
    • Href - The value of the href where the key points to.
    • 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.
Select the Target Element Section
This section can be used to target a specific element inside the target resource.
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.
Preview Pane
Displays the content that will be references.
Source Pane
Displays the XML source code of the element to be referenced.
Once you click Insert or Insert and close, the configured cross reference is inserted into your document.
Tip: You can easily insert multiple cross references by keeping the dialog box opened, using the Insert button.

Using Copy/Paste Actions to Insert a Cross Reference

Oxygen XML Editor also includes support for inserting cross references with simple copy/paste actions. The copied content must be an entire DITA XML element with an ID attribute or a topicref. Also, the location in the document where you paste the link 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. You can paste the link as a cross reference with the link expressed in an href attribute or in a keyref attribute.

To insert a cross reference link (expressed in an href attribute) using copy/paste actions, follow these steps:
  1. Copy an entire DITA element that has an ID attribute assigned to it or a topicref.
  2. Place the cursor at a location, where you want to insert the link.
  3. Select the Paste as Link action from the Paste Special submenu from the contextual menu.
To insert a cross reference link (expressed in a keyref attribute) using copy/paste actions, follow these steps:
  1. In the DITA Maps Manager view, make sure that the Root map combo box points to the correct map that stores the keys.
  2. 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.
  3. Copy an entire DITA element that has an ID attribute assigned to it from a topic with an assigned key, or a topicref from a DITA map.
  4. Place the cursor at a location, where you want to insert the link.
  5. Select the Paste as Link (keyref) action from the Paste Special submenu from the contextual menu.