Reuse content with references in Oxygen

You can edit Inspire components in an XML editor that uses Oxygen functionality. If you want to reuse content fragments from other components, you can use the Oxygen-based editor to insert several types of references. You can insert content references (conref), content key references (conkeyref), or key references to metadata (keyref).

FAQs

When would I use an xref, conref or a conkeyref?

How do I use a key reference? (keyref)

To insert content that may have different values in particular circumstances, you can use keys. You can use keys to define resources (for example, URIs, metadata, or variable text strings) at the DITA map level instead of locally in each topic. In your map, when you add a link to the content you want to reuse, you define a word as a key. Then, in your topic, you link to that key word. This way, if you need to change the referenced content, you only have to change your map file, rather than change every place you've referenced the content in your topics.

For example, in your map, add a link to the content you want to reuse, and define a key word:

<topicref href=global_definitions.dita keys="dictionary"/>

Then, in your topic, to insert the linked content, just use the key:

<xref keyref="dictionary"/>

Can I copy a link between components?

Yes.

When you're working on a document in the Oxygen-based editor, you can reuse content from other components by creating a cross-reference. After creating a cross-reference, you can copy it and paste the link into a different component.

  • Make sure you select both the link icon and entire link text when copying.

For more help, read Copy a cross reference between components.

What happens if I delete the text that's referenced in another component?

When you edit content in the Oxygen editor, if you delete content that's reference by another component, you see a confirmation message: Are you sure, you are attempting to delete one or more referenced element? Deleting these elements will create invalid links in Inspire.

You can decide if you want to:

  • To leave the content and cancel the deletion of the content, click No. This keeps all reference links valid.
    • As a best practice, you should find where the content is linked and remove the link in the other component.
    • Then you can come back and delete this content without creating invalid links.
    • Follow the steps in See where a component is used.
  • To force the content to be deleted and break reference links, click Yes. This creates invalid links in other components.

Why do I have to select a root map?

You can define a hierarchical structure of submaps and establish a key space that defines the keys used in all the other DITA maps and topics in a root map. Specifying the correct root map helps to prevent validation problems when you work with keyrefs and also acts as the foundation for content completion. If you define keys in a root map they're available in the submaps that are contained within the root map. However, it's considered best practice to create a separate submap that contains all key definitions. Then you can reference that submap in the root map. This makes it easier to manage since they're all in one location. When you want to add a reference to a key, you must have these two items ready:

  • DITA root map
  • Defined keys

The oxygen-based editor requires you to specify a root map and will step you through the process of selecting one for a component.

Why do I see a loading circle when inserting multiple conrefs or cross-references?

The Content References and Choose Cross-references screens may take time to resolve references. If this is the case, you see a loading icon to indicate the system is working before Inspire displays the elements.

How do I know my reference is up-to-date?

To refresh links and references to ensure the most recent information is being displayed, in the Oxygen editor, go to the toolbar and click Refresh references.

Whenever you refresh references, Inspire automatically:

  • Saves the changes locally
  • Submits the changes to the database
  • Reloads the content in the editor

Can I reference non-DITA files?

You can add references to other types of content:

Are ditabase files supported?

Yes. Inspire now supports content references to ditabase topics. A ditabase topic is a composite topic. Before maps, ditabase was used to collect multiple topics and structure them within a single topic file.

When working with ditabase files, you can do the following:

  • Import a ditabase file and Inspire recognizes it.
  • Create a reference to a ditabase topic in Oxygen and the link resolves without errors.
  • When you click Save and Submit, Inspire creates a valid reference.
  • See Details about the component and on the References tab.
  • See Details about the component and on the Where used tab.
  • Manage relationships for the topic and update the ditabase reference.
  • Publish the topic without errors related to the ditabase reference.

How do I create conkeyrefs that resolve correctly?

A conkeyref requires that the topic be opened from a map.

  • The @conkeyref attribute enables authors to share DITA topics that reuse content.
  • It also enables map authors to specify different key definitions for common keys.

In Inspire, you can now create conkeyrefs that resolve as conkeyrefs instead of conrefs.

  • Conkeyrefs are helpful in a scenario where you produce content for a product that has to be different for different audiences. For example, you create documentation for two different business partners and the business names must differ.
  • Simply using the @conref attribute does not work in Inspire where every DITA topic is addressed by a globally-unique identifier (GUID).

To use conkeyrefs in Inspire:

  • Authors reference the reusable content in their topics by using the @conkeyref attribute.
  • Authors create two different topics; one topic contains elements appropriate for one business partner, and the other topic contains elements appropriate for the second partner.

Note that each reuse topic must use the same element types (or compatible specializations) and values for the @id attribute.

  • The two versions of the DITA maps each contain different key definitions for the key name "reuse".

This associates a key with the topic that contains the appropriate reusable elements.

  • When each of the DITA maps is published, the elements that are referenced by @conkeyref will use the reuse topic that is referenced by the <keydef> element in the map.

For an example using conkeyrefs, read the Oxygen help: Example: conref redirection.

Why am I asked to submit my changes again?

An administrator can turn on an optional feature to help you manage referenced content. You only see a confirmation in the Oxygen editor after you click Save and Submit if:

  • Your administrator has enabled the SubmitConfirmation option.
  • You are making changes to content that is referenced by another component.

In the Oxygen editor, if both of the above conditions are true, after you click Save and Submit, you see the following screen:

You can see the component that will be affected by your updates on the Where used screen.

You can choose from the following options

  • Submit. Saves the changes you made which will also appear in the other components that reference the content.
  • Save as... Opens the Save As screen to create a new component with the changes you made. This option closes the original component without saving any changes. The newly created component opens in Oxygen. This option does not update any of the other components that referenced the original component you were editing.
  • Branch. Opens the Save As Branch screen that lets you specify where to save it (target folder) and a branch label. This options saves the current content as a new branched component. This option does not update any of the other components that referenced the original component you were editing.
  • Cancel. Closes the Where used screen and returns you to the Oxygen editor. No changes are saved to the database.

In the Oxygen editor, if any of the following are true, you won't see a confirmation.

  • Your administrator has NOT enabled the SubmitConfirmation option.
  • Your administrator has enabled the SubmitConfirmation option, but you are making changes to content that is NOT referenced by another component.

In these cases, Inspire saves your changes and closes the Oxygen editor without any other interaction.