Reusing DITA Content
Reusing content is one of the key features of DITA and DITA provides several methods for reusing content. Oxygen XML Editor provides support for each of these methods.
Reusing Topics in DITA Maps
A DITA topic does not belong to any one publication. You add a DITA topic to a publication by referencing it in a map. You can reference the same topic in multiple maps.
Reusing Content with References and Keys
DITA allows you to reuse content by referencing it in another topic.
DITA provides several mechanisms for
including content by reference (conref, conkeyref,
coderef). A conref
(content reference) creates a direct reference to a specific element of another
topic. A conkeyref (content key
reference) creates a reference to a key, which then points to a specific element in
another topic. The advantage of using a conkeyref is that you can change the
element that is included by changing the key reference. For example, since keys are defined
in maps, if you include a topic in multiple maps, you can use a different key reference in
each map. A coderef references an external file that contains literal code.
Oxygen XML Editor provides support for all of these mechanisms.
While the conref and conkeyref mechanisms can be used to reference any content element, it is considered best practice to only conref or conkeyref content that is specifically set and managed as reusable content. This practice helps reduce expensive errors, such as an author accidentally deleting the source element that other topics are including by the reference. Oxygen XML Editor can help you create a reusable component from your current content.
Reusing Content with Reusable Components
DITA allows you to select content in a topic, create a reusable component from it and reference that component in other locations. Each reusable component is created as a separate file. Anytime the content needs to be edited, you only need to update it in the component file and all the locations in your topics that reference it will also be updated. This can help you to maintain continuity and accuracy throughout your documents.
Reusing Content with Variables
DITA allows you to replace the content of certain elements with a value that is pointed to by a key. This mechanism effectively means that you can create variables in your content, which you can then create multiple outputs by changing the value that the key points to. This is done by profiling the definition of the key value, or by substituting another map with a different key value.
Reusing Content with DITA 1.3 Concepts
DITA 1.3 allows you to use some advanced concepts to expand content reuse possibilities even further. Key Scopes (or scoped keys) allow you to reuse topics with variable content depending on the particular context and it maximizes reuse possibilities for keys. Branch Filtering allows you to reuse the same content that is profiled in multiple ways within the same publication, each time using a different filter.
DITA Reusable Components View
If you use a large amount of keys or reusable components in your DITA project, the DITA Reusable Components view can be quite helpful. It collects all of the keys and reusable components that are defined in the root map and presents them in a dynamic table where you can easily locate and insert references to them.
Reuse Actions in Oxygen XML Editor
Oxygen XML Editor includes some actions that are specifically designed for DITA reusable content. These actions are available in the contextual menu, the DITA menu, and some are available on the toolbar.
Reuse
Content-
This action provides a mechanism for reusing content fragments. It opens the Reuse Content dialog box that allows you to insert several types of references to reusable content at the cursor position. The types of references that you can insert using this dialog box include content references (
@conref), content key references (@conkeyref), or key references to metadata (@keyref).
- Push Current Element
- Opens the Push current element dialog box that allows content from a source topic to be inserted into another topic without any special coding in the topic where the content will be re-used.
- Edit Content Reference
- This action is available for elements with a
@conrefor@conkeyrefattribute. It opens the Edit Content Reference dialog box that allows you to edit the source location (or key) and source element of a content reference (or content key reference), and the reference details (@conref/@conkeyrefand@conrefendattributes). For more information, see Reuse Content Dialog Box. - Replace Reference with Content
- Replaces the referenced fragment (
@conrefor@conkeyref) at the cursor position with its content from it source. This action is useful if you want to make changes to the content in the currently edited document without changing the referenced fragment in its source location. If the source content includes references to other topics/resources (hrefs), the operation also resolves those references relative to the new location. Attributes are preserved according to the following priority:- Attributes from the elements in the current document that reference other content
are preserved except for attributes with a
-dita-use-conref-targetvalue. - Attributes from the referenced content are brought into the replaced elements in
the current document except for
@idattributes.
- Attributes from the elements in the current document that reference other content
are preserved except for attributes with a
- Replace All References with Content
-
Replaces all referenced fragments (
@keyref,@conref, or@conkeyref) in the current document with the content. Attributes are preserved according to the following priority:- Attributes from the elements in the current document that reference other
content are preserved except for attributes with a
-dita-use-conref-targetvalue. - Attributes from the referenced content are brought into the replaced elements in
the current document except for
@idattributes.
For keyrefs inside
<xref>or<link>elements, the@keyrefattribute is changed to an@hrefattribute, while the rest of the content for the keyref is replaced with its source content.If the source content includes references to other topics/resources (hrefs), the operation also resolves those references relative to the new location.
- Attributes from the elements in the current document that reference other
content are preserved except for attributes with a
- Remove Content Reference
- Removes the content reference (
@conrefor@conkeyref) inside the element at the cursor position. - Create Reusable Component
- Opens a dialog box that helps you to create a reusable component from the current
element or selection of elements. If the Replace selection with content
reference option is selected in the dialog box, the selection will be
replaced with a content reference (
@conref). If multiple elements are selected (for example, multiple steps or list items), the selection will be replaced with a content reference range (@conrefand@conrefend). For more information, see Creating a Reusable Content Component. - Insert Reusable Component
- Inserts a reusable component at cursor location. For more information, see Inserting a Reusable Content Component.