Inserting Links in DITA Assets

Prerequisites: Users must have permissions to check in and out assets in the CMS Assets Manager. See Creating Groups for details to set permissions.

Users can employ the Oxygen Desktop Plugin to insert CMS asset links in CMS DITA document assets directly.

Important: To insert links to other CMS document assets stored in the CMS Assets Manager, ensure the DITA root folder (i.e., the folder assigned to the rootFolderID that you provided during plugin installation) contains the folder where those document assets reside.

To insert CMS asset links in CMS DITA document assets via the Oxygen Editor plugin:

  1. Open the Oxygen XML Web Editor application.
  2. Check out the DITA document asset in Oxygen XML Editor. The document asset checks out in the CMS and displays in the main pane Editor. An unlock icon displays next to the checked-out document asset in the Ingeniux CMS Browser tree.
  3. Ensure Author mode displays as selected in the bottom-left area of the main pane.

    Author Mode

  4. Select an area within the document asset that allows image insertions, and choose one of the following steps:
    • Click the Link button in the toolbar, and select Cross Reference... in the drop-down menu.

      Insert Link via Toolbar

    • Press ENTER on your keyboard, and enter the initial letters of xref in the text field. Click the image entry that displays in the results list.

      Insert Link via Keyboard

    The Cross reference (xref) dialog displays.

    Cross Reference (xref) Dialog

  5. Choose one of the following steps:
    1. Insert a link to the DITA asset's location by selecting the Location option.
      1. Click the folder drop-down arrow in the Location field, and select Browse CMS Content. The Select CMS Resource dialog displays.

        Select CMS Resource Dialog

      2. Navigate to the link to insert in the assets tree folder structure, and click OK. The dialog closes.
    2. Insert a key to the DITA asset content by selecting the Key option.
      1. Click the Choose Key Reference button.
      2. Choose a key from the list, and click OK.
  6. Click Insert and close. The link reference displays in the document asset.

    Additional Information:

    Note the following.
    • When you select Text mode in the Oxygen XML Editor UI, the <xref> element's href attribute value displays the DITA document asset's filepath.

      Link Href Value in Oxygen Desktop Plugin UI

    • When you navigate to the CMS Assets Manager UI to view the asset in the Edit tab, the <xref> element's href attribute value displays the DITA document asset's a/ID.

      Link Href Value in CMS Assets Manager UI

    The plugin displays the xref filepaths as href values so that the references validate in the Oxygen XML Editor UI. The system stores the a/IDs in the CMS Assets Manager so that users can always move, rename, and perform other operations on assets in the CMS UI. This way, the values always update to the correct reference after users reload the Oxygen XML Editor UI or Ingeniux CMS UI.