DITA Reusable Components View

The DITA Reusable Components view is helpful if you use a large number of keys or reusable components in your DITA project. It collects all of the keys and reusable components that are defined in the root map and presents them in a side view where you can easily locate and insert references to them. It recollects the keys anytime the root map is changed or you switch the editor focus to a different file.

If the view is not displayed, it can be opened by selecting it from Window > Show View > Other. By default, it appears in the bottom-right section of the editor.

It includes the following tabs:

Keys - Displays all the keys that are defined in the root map and provides ways to easily insert references to them as cross reference links, key references, or variables. It includes a search field, some filtering and sorting options to help you find particular keys, and some contextual menu actions. It also supports drag and drop actions and double-clicking a key is the fastest way to insert a reference.
Note: If the keys are gathered from peer DITA maps (used in cross publication references), the keys that define variables are not presented.
Components - Displays all the reusable components found in the root map and provides ways to easily insert them as content references or content key references. To determine which components to display in this tab, Oxygen XML Author Eclipse plugin looks for any topicref in the root map that is marked as resource-only and then looks for elements with an assigned @id attribute value. This tab includes a search field, some filtering options, and some simple links and contextual menu actions to quickly insert references or open their source file. It also supports drag and drop and double-clicking actions.

Keys Tab

The DITA Reusable Components view collects all the keys that are defined in the current root map and displays them in the Keys tab. This tab has two view modes. The default tiles style view mode and a table style view mode.

Tiles Mode

The default tiles mode displays the keys as blocks (cards). The advantage of this display mode is that more information about each particular key can be seen even when the view is sized with a small width. Each block (card) displays the name of the key (the value of the @keys attribute), followed by its description and/or @href value, then followed by the name of the DITA map file where the key is defined.

Figure 1. DITA Reusable Components View - Keys Tab (Default tiles mode)

Table Mode

You can switch to a table style display mode by selecting the Table mode toggle action from the Settings menu. The advantage of this display mode is that more keys can be listed at once. In this mode, keys that are defined with a text value in the <navtitle> or <keyword> element have that value listed in the Description column, while keys that are defined with a value in an @href attribute have that href value listed in the Href column.

Figure 2. DITA Reusable Components View - Keys Tab (Table mode)

Both display modes in the Keys tab include a variety of features and options:

Search Filter

You can enter text in the filter field at the top of this tab to filter the list and search for specific keys.

Sorting

Tiles Mode: In the default tiles display mode, to sort the keys alphabetically in ascending order, select Sort by key name from the Settings menu.

Table Mode: In the table display mode, the following columns can be sorted by clicking the heading:

Key - The name of the key (the value of the @keys attribute).
Description - The description of the key that is obtained from its definition. Keys that are defined with a text value in the <navtitle> or <keyword> element have that value listed in this column.
Href - Keys that are defined with a value in an @href attribute have that href value listed in this column.
Definition Location - The name of the DITA map where the key is defined.

Double-Click Mechanism

You can double-click any key listed in this tab to insert a key reference at the current cursor position or surrounding the current selection.

If the selected key points to an @href value, it is inserted as a cross reference link (xref).
If the selected key is a reference to an image, it is inserted as an <image> element.
If the selected key does not have an associated @href, it is inserted as a variable reference (ph).

Drag and Drop Mechanism

You can drag a key from this tab and drop it in the main editor to insert a key reference at the current cursor position.

If the selected key points to an @href value, it is inserted as a cross reference link (xref).
If the selected key is a reference to an image, it is inserted as an <image> element.
If the selected key does not have an associated @href, it is inserted as a variable reference (ph).

Contextual Menu Actions

Insert as Link

Inserts a cross reference link (xref) to the selected key at the current cursor position or surrounding the current selection.

Insert as Variable

Inserts a variable reference (ph) to the selected key at the current cursor position or surrounding the current selection. However, if the selected key is a reference to an image, this action inserts the key reference in an <image> element.

Insert as Keyref

Presents a submenu with all the elements that can be inserted at the current cursor position. Selecting an element will insert that element at the current cursor position or surrounding the current selection with a @keyref attribute and its value set to the selected key.

Insert as Figure

Available if the selection is an image, it inserts the image inside a figure element (<fig>). Note that the <title> element of the inserted figure will be empty.

Rename Key

Opens a refactoring wizard where you can easily rename the key and define the scope of the operation. It also updates all references to it.

Notes:

This action does not work on DITA 1.3 key scopes.
This action is only available if the DITA map opened in the DITA Maps Manager is also selected as the Root map.

Go to Definition

Opens the DITA map where the key is defined.

Search References

Searches for all references to the selected key in the entire DITA map structure.

Group by Definition Location (Available in Table mode only)

A toggle action that can be used to group (and sort) all the keys based on the value in the Definition Location column.

Settings Menu

This menu includes the following options:

Filtering Options

Show all - Shows all defined keys found in the current root map.
Show only variables - Filters the keys to show only those defined as variable references.
Show only maps and topics - Filters the keys to show only those that reference DITA maps or topics.
Show only multimedia resources - Filters the keys to show only those that reference multimedia resources (such as images).
Show only external resources - Filters the keys to show only those that reference external resources (such as web links).

Sort by key name (Available in Tiles mode only)

Sorts the keys alphabetically in ascending order.

Table mode

A toggle action that switches between the table and tiles display modes.

Components Tab

The DITA Reusable Components view collects all the topics from the current root map that are marked as resource-only, then collects the reusable components from those topics, and displays them in the Components tab. To set a topic as resource-only, the <topicref> in the DITA map file must have a @processing-role attribute set like this:

<topicref href="topics/randomize-xml-content.dita" processing-role="resource-only"/>

The DITA Reusable Components view considers topic references that contain processing-role="resource-only" to be candidates to contain reusable components. The reusable components inside these topics are collected from all elements that have an ID specified. These reusable components are displayed in the Components tab along with the file name and the specific names of the elements that contain an ID attribute.

Figure 3. DITA Reusable Components View - Components Tab

The Components tab includes the following features and options:

Search Filter

You can enter text in the filter field at the top of this tab to filter the list and search for specific content inside the list of reusable components. This field supports many of the Lucene-based search patterns, such as wildcards (* or ?), boolean operators (AND, OR, NOT), fuzzy searches (~), boosting searches (^), and more.

Settings Menu

This menu includes the following options:

Compact Mode: You can use this toggle action to switch the display for the Components tab to a compact visualization mode. When switched to Compact mode, fewer details are shown for each component, but more components are displayed in the view.
Reindex: You can use this action force a re-indexing of the reusable components.

Show Elements of Type

You can use this drop-down list to select specific types of elements to be displayed in the list of components. This can help you narrow down the list of possible source elements that you can select.

Source File(s)

You can use this combo box to search for specific source files (the topics that contain reusable components) or select a file from its drop-down list. You can also use wildcards (such as * or ?) in this field.

Double-Click Mechanism

You can double-click any reusable component listed in preview window in this tab to insert it as a content reference or content key reference at the current cursor position or replace the current selection.

If the parent topic of the selected component has a key defined, it is inserted as a content key reference (conkeyref).
If the parent topic of the selected component does not have a key defined, it is inserted as a content reference (conref).

Drag and Drop Mechanism

You can drag a reusable component from the preview window in this tab and drop it in the main editor to insert a content reference or content key reference at the current cursor position.

If the parent topic of the selected component has a key defined, it is inserted as a content key reference (conkeyref).
If the parent topic of the selected component does not have a key defined, it is inserted as a content reference (conref).

Hover and Click Actions

If you hover over a component shown in the preview window, you have access to the following link actions:

Insert: Inserts the component as a content reference or content key reference at the current cursor position or replaces the current selection. If the parent topic has a key defined, it is inserted as a content key reference (conkeyref). Otherwise, it is inserted as a content reference (conref).
Open: Opens the source file that contains the reusable component.

Contextual Menu Actions

Insert Content Reference: Inserts the component as a content reference (conref) at the current cursor position or replaces the current selection.
Insert Content Key Reference: Inserts the component as a content key reference (conkeyref) at the current cursor position or replaces the current selection. This action is only available if the parent topic has a key defined.
Go to Definition: Opens the source file that contains the reusable component.
Search References: Searches for all references to the selected component in the entire DITA map structure.