DITA Maps Manager
Oxygen XML Editor provides a view for managing and editing DITA maps. The DITA Maps Manager view presents a DITA map as a tree or table of contents. It allows you to navigate the topics and maps, make changes, and apply transformation scenarios to obtain various output formats. By default, it is located to the left of the main editor. If the view is not displayed, it can be opened by selecting it from the menu.
The DITA Maps Manager includes a variety of useful actions to help you edit and organize the structure of your DITA maps and topics. The actions that are available and their functions depend on the type of nodes that are selected in the DITA Maps Manager. If you select multiple sibling nodes, the result of the actions will be applied to all the selected nodes. If you select multiple nodes that are not on the same hierarchical level, the actions will be applied to the parent node and the child nodes will inherit certain attributes from the parent node.
An icon that represents its type of DITA resource is displayed on the left
side of each node. For example, a DITA Map is displayed with the icon, a DITA
Topic is displayed with , a DITA Task is displayed with , etc. Any node that has
processing-role="resource-only"
set in its properties is displayed with a
gray dot in the bottom-right corner of the icon ().
The title of the DITA resource is also displayed for each node. The
displayed title depends on how the referenced resource is configured within the DITA
structure. For example, the title could be resolved as the text value inside the referenced
topic's <title>
element or the value of the @navtitle
attribute specified within the DITA map. For non-DITA resources that are referenced in a DITA
map, the file name of the resource is usually displayed for the title. However, it is possible
to obtain the title from the referenced non-DITA documents by dynamically converting them
using the process described in: Dynamic Word, Excel, OpenAPI, HTML, Markdown to DITA Conversion. In this case, the
document title obtained from the conversion process is displayed as the resource title in the
DITA Maps Manager.
Opening Maps in the DITA Maps Manager
- To open a submap in its own tab, simply double-click it (or right-click it and select Open).
- If you open a file with a .ditamap or
.bookmap extension (from the Project view or a system browser), a dialog box is
opened that offers you the choice of opening it in the DITA Maps
Manager or the XML editor.Note: If you select the Do not show the dialog again option, it will always be opened in the method that you choose and you will not be asked in the future. However, you can reset this by selecting the Always ask choice for the When opening a map option in the DITA preferences page.
- Right-click a map file in the Project view and select .
- If you have a DITA map file open in the XML editor, you can right-click the title tab and select Open in DITA Maps Manager View.
By default, when a map is opened in the DITA Maps Manager, its index is automatically refreshed. You can disable this feature by deselecting the Refresh index when opening a map in DITA Maps Manager option in the Open/Find Resource preferences page.
Submap Nodes
If your root map (main DITA map) references other maps (submaps), they can be expanded and you can navigate their content in the DITA Maps Manager.
References within those submaps are not editable, by default, unless you open the submap separately in its own tab. If you want to be able to edit submaps when the main (root/parent) map is open in the DITA Maps Manager, go to and select the Allow referenced submaps to be edited option. The references within submap nodes are shown with a gray background if they are not editable.
Moving Nodes in the DITA Maps Manager
You can move topics or nodes within the same map, or other maps, by dragging and dropping them into the desired position. You can arrange the nodes by dragging and dropping one or more nodes at a time. You can arrange multiple topics by dragging them while pressing the Ctrl or Shift key. Drop operations can be performed before, after, or as child of the targeted node.
Operations include:
- Copy
- Select the nodes you want to copy and start dragging them. Before dropping them in the appropriate place, press and hold the Ctrl key. The mouse pointer changes to a symbol to indicate that a copy operation is being performed.
- Move
- Select the nodes you want to move and drag and drop them in the appropriate place.
- Promote (Alt + LeftArrow) /Demote (Alt + RightArrow)
- You can move nodes between child and parent nodes by using the Promote (Alt + LeftArrow) and Demote (Alt + RightArrow) operations.
DITA Maps Manager Toolbar
The toolbar includes the following actions (also available in the DITA Maps menu) and their availability depend on the nodes that are selected:
- New DITA Map
- Opens the New Document wizard that you can use to create a new DITA map document.
- Open Drop-down Menu
- You can use this drop-down menu to open new DITA maps or to reopen
recently viewed maps. The drop-down menu contains the following:
- List of recently viewed DITA maps that can be selected to reopen them.
- Clear history - Clears the history list of the recently viewed DITA maps.
- Open - Allows you to open the map in the DITA Maps Manager view. You can also open a map by dragging it from the file system explorer and dropping it into the DITA Maps Manager view.
- Open URL - Displays the Open URL dialog box where you can specify a URL (defined by a protocol, host, resource path, and an optional port) or use the browsing actions in the Browse for remote file drop-down menu.
- Save (Ctrl + S (Meta + S on macOS))
- Saves the current DITA map.
- Validation drop-down menu
- This drop-down menu contains options for validating the current map. The following
options are available:
- Validate and Check for Completeness
- Opens the DITA Map Completeness Check dialog box where you can configure options for checking the validity and integrity of the map.
- Validate
- Validates the current map that is open in the DITA Maps Manager using the associated validation scenarios.
- Configure Validation Scenario(s)
- Use this option to configure validation scenarios and their associations.
- Generate Metrics Report
- Generate a report that contains statistics about the entire DITA map in HTML format.
- Apply Transformation Scenario(s)
- Applies the DITA Map transformation scenario that is associated with the current map.
- Configure Transformation Scenario(s)
- Opens the Configure Transformation Scenarios(s) dialog box where you can edit or create transformation scenarios or associate a DITA Map transformation scenario with the current map.
- Open Map in Editor with Resolved Topics
-
Opens the DITA map in the main editor area with content from all topic references expanded in-place. Referenced content is presented as read-only by default. To edit it, you must use the Edit Reference contextual menu action to open the source topic that contains the referenced content.
If you want to edit the referenced topics directly without having to open the source document, go to Allow referenced content to be edited option. Since a single topic may be referenced in multiple places in the DITA map, be careful not to make conflicting changes to that topic.
and select theTip: If you want to print the expanded content, you should consider changing selecting + Print ready from the Styles drop-down menu on the toolbar. - Open Map in Editor
- For complex operations that cannot be performed in the simplified DITA
Maps Manager view (for instance, editing a relationship table) you can
open the map in the main editing area. Note: You can also use this action to open referenced DITA maps in the Editor.
- Link with Editor
- Toggles the synchronization between the file path of the current editor and the
selected topic reference in the DITA Maps Manager view. If
enabled, it results in the following types of synchronizations:
- If you select a topic tab in the main editing area and it is referenced in the map currently opened in the DITA Maps Manager, the reference to that topic is selected in the DITA Maps Manager.
- If you have a map opened in both the DITA Maps Manager and the main editor, selecting the map tab in the main editing area opens that map in the DITA Maps Manager.
- If you have a map opened in both the DITA Maps Manager and the main editor (Author mode), selecting one or more topicrefs in the DITA Maps Manager will also select the same topicrefs in the main editor.
- If you have a map opened in both the DITA Maps Manager and the main editor (Author mode), selecting one or more topicrefs in the main editor will also select the same topicrefs in the DITA Maps Manager.
- Settings
-
- Show extended toolbar
- Toggles whether or not the extended toolbar will be displayed in the DITA Maps Manager toolbar.
- Show context toolbar
- Toggles whether or not the Context option will be displayed in the DITA Maps Manager toolbar.
- Show topic titles
- Toggles how topics are presented in the DITA Maps
Manager. If selected, the title of each topic is shown.
Otherwise, the file path (value of the
@href
attribute) for each topic is shown. - Show key reference values
- Toggles how key references are presented in the DITA Maps
Manager. If selected, the value of the
@keyref
attribute for each key reference is shown.
- Context Root Map Drop-down menu
- The drop-down menu displayed after Context can be used to specify the DITA root map) that Oxygen XML Editor uses to define a hierarchical structure of submaps and to establish a key space that defines the keys that are propagated throughout the entire map structure. For more information, see Selecting a Root Map.
- Choose context root map browsing/search menu
- You can use this drop-down menu to browse or search for root maps with
the following choices:
- Browse for local file - Opens a local file browser dialog box, allowing you to select a local root map.
- Browse for remote file - Displays the Open URL dialog box that allows you to select a remotely stored root map.
- Browse for archived file - Displays the Archive Browser that allows you to browse the content of an archive and choose a root map.
- Browse Data Source
Explorer - Opens the Data Source Explorer that allows you to browse
the data sources defined in the Data Sources
preferences page.Tip: You can open the Data Sources preferences page by using the Configure Database Sources shortcut from the Open URL dialog box.
- Search for file - Displays the Find Resource dialog box to search for a root map.
- Choose context from main files - Allows you to choose a context root map from the DITA maps and the DITA-OT project files that are set in the Main Files folder.
- Profiling/Conditional Text Drop-down Menu
- You can use this drop-down menu to select and apply a defined profiling condition
set to filter the content based on that condition set. The drop-down menu
also contains the following other options:
- Show Profiling Colors and Styles - Select this option to turn on conditional styling. To configure the colors and styles open the Preferences dialog box and go to .
- Show Profiling Attributes - Select this option to display the values of the profiling attributes at the end of the titles of topic references. When selected, the values of the profiling attributes are displayed in both the DITA Maps Manager view and in the Author view.
- Show Excluded Content - Controls if the content filtered out by a particular condition set is hidden or grayed-out in the editor area and in the Outline and DITA Maps Manager views. When this option is selected, the content filtered by the currently applied condition set is grayed-out. To show only the content that matches the currently applied condition set, deselect this option.
- Profiling Settings - Opens the preferences page for adding and editing the profiling conditions that you can apply in the DITA Maps Manager view and the Author mode editing pane. When a profiling condition set is applied, the keys that are defined in the DITA map are gathered by filtering out the excluded content.
- Insert Topic Reference
- Opens the Insert Reference dialog box that allows you to insert references to targets such as topics, maps, topic sets, or key definitions.
- Refresh References
- You can use this action to manually trigger a refresh and update of all referenced documents. This action is useful when the referenced documents are modified externally. When they are modified and saved from Oxygen XML Editor, the DITA map is updated automatically.
- Edit Properties
- Opens the Edit Properties dialog box that allows you to configure the properties of a selected node. For more details about this dialog box, see Edit Properties Dialog Box.
- Edit Attributes
- Opens a small in-place editor that allows you to edit the attributes of a selected node. You can find more details about this action in the Attributes View in Author Mode topic.
- Delete
- Deletes the selected node.
- Move Up
- Moves the selected node up within the DITA map tree.
- Move Down
- Moves the selected node down within the DITA map tree.
- Promote(Alt + LeftArrow)
- Moves the selected node up one level to the level of its parent node.
- Demote(Alt + RightArrow)
- Moves the selected node down one level to the level of its child nodes.
Resources
For more information about the DITA Maps Manager view and many of its features, watch our video demonstration: