DITA Reusable Components View

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).
• Show only keys with closest relative key scope - Filters the presented keys to hide the fully qualified key scope paths and show only the relative key references that have the closest relative key scope path in the current context. This toggle option can be combined with any of the other filtering options. It is deselected by default. This option always remains synchronized with this same option in the Media tab so changing it one of the tabs also changes it for the other.

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.

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.

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.

Search Filter

You can enter text in the filter field at the top of this tab to filter the list and search for specific media resource key or file names in the list of available resources.

Resource Type Filter

You can quickly show resources of a specific type by clicking one of the type buttons (Images, Audio, Video, Others).

Settings Menu

This menu includes the following options:

Sort by date

Sorts the presented resources based on both the date when they were last modified and the date they were created.

Show only keys with closest relative key scope

Filters the presented keys to hide the fully qualified key scope paths and show only the relative key references that have the closest relative key scope path in the current context. This toggle option can be combined with any of the other filtering options. It is deselected by default. This option always remains synchronized with this same option in the Keys tab so changing it one of the tabs also changes it for the other.

Configure working sets

Use this option to define folders where the media resources will be gathered. The Media tab will include audio, image, and video resources collected from the current root map as well as media resources located in the folders defined as active working sets. The working sets are defined at project level so that they can be easily shared with others. To save working sets in the global user-specific settings instead, in the Preferences > Project Level Settings page you can uncheck the Save DITA media working sets at project level checkbox.

Reload

Refreshes the list of displayed media resources. This is useful if resources were recently added in the searched folders.

Double-Click Mechanism

You can double-click any media resource in the list to add a reference to it.

Drag and Drop Mechanism

You can drag a media resource from the list and drop it in the main editor to add a reference to it.

Contextual Menu Actions

Insert As Image Reference

Inserts an image reference. If the resource is referenced using a key in the DITA map, an indirect reference using the defined key will be used. Otherwise, the reference will point directly to the resource location.

Insert As Audio Reference

Inserts an audio reference. If the resource is referenced using a key in the DITA map, an indirect reference using the defined key will be used. Otherwise, the reference will point directly to the resource location.

Insert As Video Reference

Inserts a video reference. If the resource is referenced using a key in the DITA map, an indirect reference using the defined key will be used. Otherwise, the reference will point directly to the resource location.

Insert As Embedded Reference

Inserts as an embedded reference. If the resource is referenced using a key in the DITA map, an indirect reference using the defined key will be used. Otherwise, the reference will point directly to the resource location.

Insert as Link

Inserts a link to the resource, either as a DITA <xref> or <link>, depending on the cursor position.

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.

Preview

Shows the selection in an Image Preview side view.

Open in System Application

Opens the default system editor/viewer associated with the resource type.

Show in Explorer/Finder

Opens the default file browser at the specific folder where the resource is located.

Items in the Media tab are presented in the following order:

• Key definitions are always presented first, in document order.
• Resources defined and collected from working sets are sorted alphabetically by name, for each folder separately.