DITA Maps organize topics for output to a specific deliverable, including generating navigation files and links to related topics. <oXygen/> provides a special DITA Maps editing view.
The DITA Maps Manager view presents maps in a simplified table-of-contents manner allowing the user to easily navigate the referred topics, make changes and perform transformations to various output formats using the DITA-OT framework bundled with <oXygen/>.
You can open a map file from Project in the DITA Maps Manager view by right clicking it and choosing Open in DITA Maps Manager. The titles of the referenced resources will be resolved dynamically when navigating the tree. After the map is opened in the Manager you can open it in the main editor for further customization using the Open map in editor toolbar action.
![[Note]](img/note.gif) | Note |
|---|---|
A map opened from WebDAV can be locked when it is opened in DITA Maps Manager by checking the option Lock WebDAV files on open to protect it from concurrent modifications on the server by other users. If other user tries to edit the same map he will receive an error message and the name of the lock owner. The lock is released automatically when the map is closed from <oXygen/> DITA Maps Manager. |
The following general actions can be performed on an opened DITA Map :
-
Open
Allows opening the DITA Map in the DITA Maps Manager view.
-
Open URL
Allows opening remote DITA Maps in the DITA Maps Manager view. See Open URL for details.
-
Save
Allows saving the currently opened DITA Map.
-
Apply Transformation Scenario
Allows the user to start the DITA ANT Transformation scenario associated with the opened map. For more transformation details see here.
-
Configure Transformation Scenario
Allows the user to configure a DITA ANT Transformation scenario for the opened map. For more transformation details see here.
-
Refresh References
Sometimes after a topic was edited and its title changed the topic's title needs to be also updated in the DITA Maps manager view. You can use this action to refresh and update titles for all referred topics.
-
Open map in editor
For complex operations which cannot be performed in the simplified DITA Maps view (like editing a relationship table) you can open the map in the main editing area. See more about editing a map in the main edit area here.
![[Tip]](img/tip.gif) | Tip |
|---|---|
The additional edit toolbar can be shown by clicking the "Show/Hide additional toolbar" expand button located on the general toolbar. |
The following edit actions can be performed on an opened DITA Map:
-
Insert Topic Reference
Inserts a reference to a topic file. See more about this action here.
-
Insert Topic Heading
Inserts a topic heading. See more about this action here
-
Insert Topic Group
Inserts a topic group. See more about this action here.
-
Edit properties
Edit the properties of a selected node. See more about this action here.
-
Edit attributes
Edits the attributes of a selected node. A dialog is presented allowing the user to see and edit the attributes of the selected node. See here for more details about editing attributes.
-
Delete
Deletes the selected nodes.
-
Move Up
Moves the selected nodes in front of their respective previous siblings.
-
Move Down
Moves the selected nodes after their next respective siblings.
-
Promote
Moves the selected nodes after their respective parents as a siblings.
-
Demote
Moves the selected nodes as children to their respective previous siblings.
The contextual menu contains, in addition to the edit actions described above, the following actions:
- Open in editor
Open in the editor the resources referred by the selected nodes
- Cut, Copy, Paste, Undo, Redo
Common edit actions with the same functionality as those found in the text editor
- Paste before, Paste after
Will paste the content of the clipboard before respectively after the selected node.
- Append Child/Insert After
- Topic reference
Append/Insert a topic reference as a child/sibling of the selected node
- Topic reference to the current edited file
Append/Insert a topic reference to the current edited file as a child/sibling of the selected node
- Topic heading
Append/Insert a topic heading as a child/sibling of the selected node
- Topic group
Append/Insert a topic group as a child/sibling of the selected node
You can also arrange the nodes by dragging and dropping one or more nodes at a time. Drop operations can be performed before, after or as child of the targeted node. The relative location of the drop is indicated while hovering the mouse over a node before releasing the mouse button for the drop.
Drag and drop operations allow you to:
- 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(META key on Mac). The mouse pointer should change to indicate that a copy operation will be performed.
- Move
Select the nodes you want to move and drag and drop them in the appropriate place.
- Promote / Demote
You can move nodes between child and parent nodes which ensures both Promote and Demote operations.
| Tip |
|---|---|
You can open and edit linked topics easily by double clicking the references or by right-clicking and choosing "Open in editor". If the referenced file does not exist you will be allowed to create it. By right clicking the map root element you can open and edit it in the main editor area for more complex operations. You can decide to open the reference directly in the Author page and keep this setting as a default. |
| Note |
|---|---|
Some of the common actions from the main application menu/toolbar also apply to the DITA Maps Manager when it has focus. These actions are:
The Save all action applies to all editors opened in either <oXygen/> work area or the DITA Maps Manager. |
The topicref element identifies a topic (such as a concept, task, or reference) or other resource. A topicref can contain other topicref elements, allowing you to express navigation or table-of-contents hierarchies, as well as implying relationships between the containing topicref and its children. You can set the collection-type of a container topicref to determine how its children are related to each other. You can also express relationships among topicref's using group and table structures (using topicgroup and reltable). Relationships end up expressed as links in the output (with each participant in a relationship having links to the other participants by default).
A reference to a topic file may be inserted both from the toolbar action and the contextual node actions. The same dialog can be used to insert references to maps or links to non-dita files like pdf's.
By using the Insert Topic Reference Dialog you can easily browse for and select the source topic file. The Target combo box shows all available topics that can be targeted in the file. Selecting a target modifies the Href value to point to it. The Format and Scope combos are automatically filled based on the selected file. You can specify and enforce a custom navigation title by checking the Navigation title checkbox and entering the desired title.
The file chooser located in the dialog allows you to easily select the desired topic. The selected topic file will be added as a child/sibling of the current selected topic reference. You can easily insert multiple topic references by keeping the dialog opened and changing the selection in the DITA Maps Manager tree.
The topichead element provides a title-only entry in a navigation map, as an alternative to the fully-linked title provided by the topicref element.
A topic heading can be inserted both from the toolbar action and the contextual node actions.
By using the Insert Topic Heading Dialog you can easily insert a topichead element. The Navigation title is required but other attributes can be specified as well from the dialog.
The topicgroup element identifies a group of topics (such as a concepts, tasks, or references) or other resources. A topicgroup can contain other topicgroup elements, allowing you to express navigation or table-of-contents hierarchies, as well as implying relationships between the containing topicgroup and its children. You can set the collection-type of a container topicgroup to determine how its children are related to each other. Relationships end up expressed as links in the output (with each participant in a relationship having links to the other participants by default).
A topic group may be inserted both from the toolbar action and the contextual node actions.
By using the Insert Topic Group Dialog you can easily insert a topicgroup element. The Type, Format, Scope and Collection type attributes can be specified from the dialog.
The Edit properties action, available both on the toolbar and on the contextual menu, is used to edit the properties of the selected node. Depending on the selected node, the action will perform the following tasks:
If a topicref element is selected, the action will show a dialog similar with the Insert Topic Reference dialog allowing the editing of some important attributes.
If a topichead element is selected, the action will show a dialog similar with the Insert Topic Heading dialog allowing the editing of some important attributes.
If a topicgroup element is selected, the action will show a dialog similar with the Insert Topic Group dialog allowing the editing of some important attributes.
If the map's root element is selected then the user will be able to easily edit the map's title using the Edit Map title dialog:
By using this dialog you can also specify whether the title will be specified as the title attribute to the map or as a title element (for DITA-OT 1.1) or specified in both locations.