Reusing content

The DITA framework allows reusing content from other DITA files with a content reference in the following ways:

DITA makes the distinction between local content, that is the text and graphics that are actually present in the element, and referenced content that is referred by the element but is located in a different file. You have the option of displaying referenced content by setting the option Display referred content that is available from menu OptionsPreferences+Editor+Pages+Author.

 Working with content references

The DITA feature called conref (short for "content reference") enables a piece of content to be included by reference in multiple contexts. When you need to update that content, you need to update it in only one place. Typical uses of content references are for product names, warnings, definitions or process steps.

You can use either or both of the following strategies for managing content references:

  • Reusable components: With this strategy, you create a new file for each piece of content that you want to reuse.

  • Arbitrary content references: You may prefer to keep many pieces of reusable content in one file. For example, you might want one file to consist of a list of product names, with each product name in a "phrase" (<ph> element) within the file. Then, wherever you need to display a product name, you can insert a content reference that points to the appropriate <ph> element in this file.

    This strategy requires more setup than Reusable Components, but makes easier centrally managing the reused content.

<oXygen/> XML Author creates a reference to the external content by adding a conref attribute to an element in the local document. The conref attribute defines a link to the referenced content, made up of a path to the file and the topic ID within the file. The path may also reference a specific element ID within the topic. Referenced content is not physically copied to the referencing file, but <oXygen/> XML Author displays it as if it is there in the referencing file. You can also choose to view local content instead of referenced content, to edit the attributes or contents of the referencing element.

 Reusable component

When you need to reuse a part of a DITA topic in different places (in the same topic or in different topics) it is recommended to create a separate component and insert only a reference to the new component in all places. Below are the steps for extracting a reusable component, inserting a reference to the component and quickly editing the content inside the component.

  1. Select with the mouse the content that you want to reuse in the DITA file opened in Author mode.

  2. Start the action Create Reusable Component that is available on the DITA menu, the Author framework actions toolbar and the contextual menu of the Author editor.

  3. In the combo box Reuse Content select the DITA element with the content that you want to extract in a separate component. The combo box contains the current DITA element where the cursor is located (for example a p element - a paragraph - or a step or a taskbody or a conbody etc.) and also all the ancestor elements of the current element.

  4. In the Description area you should enter a textual description for quick identification by other users of the component.

  5. If you want to replace the extracted content with a reference to the new component you should leave the checkbox Replace selection with content reference with the default value (selected).

  6. Press the Save button which will open a file system dialog where you have to select the folder and enter the name of the file that will store the reusable component.

  7. Press the Save button in the file system dialog to save the the reusable component in a file. If the checkbox was selected in the Create Reusable Component dialog the conref attribute will be added to the element that was extracted as a separate component. In Author mode the content that is referenced by the conref attribute is displayed with grey background and is read-only because it is stored in other file.

  8. Optionally, to insert a reference to the same component in other location just place the cursor at the insert location and run the action Insert Reusable Component that is available on the DITA menu, the Author framework actions toolbar and the contextual menu of the Author editor. Just select in the file system dialog the file that stores the component and press the OK button. The action will add a conref attribute to the DITA element at the insert location. The referenced content will be displayed in Author mode with grey background to indicate that it is not editable.

  9. Optionally, to edit the content inside the component just click on the open icon at the start of the grey background area which will open the component in a separate editor.

 Insert a direct content reference

You should follow these steps for inserting an element with a content reference (conref) attribute that points to an element that is not in a reusable component file.

  1. Start one of the actions Insert a DITA Content Reference and Insert a DITA Content Key Reference.

  2. In the dialog Insert Content Reference select the file with the referenced content in the URL field.

  3. In the tree that presents the DITA elements of the specified file that have an id attribute you have to select the element or the interval of elements that you want to reference. The conref field will be filled automatically with the id value of the selected element. If you select an interval of elements the conrefend field will be filled with the id value of the element that ends the selected interval.

  4. Press the OK button to insert in the current DITA file an element with the same name and with the same conref attribute value (and optionally with the same conrefend attribute value) as the element(s) selected in the dialog.