Adding Topics to a DITA Map

When you are working in DITA, there are several approaches that you can use to create topics and maps. You can start by first creating topics and then assembling your finished topics into one or more documents by creating one or more maps, or you can start by creating a map and then adding new topics to it as you work.

The topics-first approach is generally more appropriate if you intend to do a lot of content reuse, as it encourages you to think of each topic as an independent unit that can be combined with other topics in various ways. The map-first approach will be more familiar to you if you are used to creating books or manuals as a whole. Oxygen XML Author Eclipse plugin supports both approaches.

A DITA map organizes content hierarchically, so you can add a topic as a child of the map root element or as a child or sibling of any item already in the map. Therefore, the first step to adding a topic to a map is always to choose the place it will be inserted into the map.

Adding Existing Topics to a Map

At the XML-level, a topic is added to a map by adding a reference to the map that points to the topic. There are a variety of reference types that you can use. The default type is the <topicref> element. See the DITA documentation for the full range of reference elements and their uses. Oxygen XML Author Eclipse plugin provides several tools for inserting reference elements into a map:

Using the Insert Reference Dialog Box

The Insert Reference dialog box allows you to create various reference types and configure the most commonly used attributes. You can open the Insert Reference dialog box with any of the following methods:

Right-click an item in the current map where you want to add the reference, select Append Child, Insert Before, or Insert After and select the type of reference to enter.
If the topic you want to add is currently open in the editor, you can right-click an item in the current map where you want to add the reference and select Reference to the currently edited file.
Selecting an item in the map and click the Insert Reference button from the DITA Maps Manager toolbar.
Select Insert Reference from the DITA Maps menu.

Dragging and Dropping a File into the DITA Maps Manager

You can add a topic to a DITA map by dragging and dropping the file into the DITA Maps Manager. You can drag and drop files from any of the following:

Your OS file system explorer.
The Project Explorer view.

Adding topics this way will not open the Insert Reference dialog box, but you can adjust all the same properties by invoking the contextual menu from the topic and selecting Edit Properties.

Adding a New Topic to a Map

To add a new topic to a map, follow these steps:

In the DITA Maps Manager, right-click the node in the current map where you want to add the new topic.
Select one of the following actions:
- Append Child > New - Select this action to insert the new topic as a child of the selected node. This action opens a New file dialog box that allows you to select the type of document and assists you with naming it. After you have configured your new topic, click Create.
- Insert Before > New - Select this action to insert the new topic as a sibling to the current node, before it. This action opens a New file dialog box that allows you to select the type of document and assists you with naming it. After you have configured your new topic, click Create.
- Insert After > New - Select this action to insert the new topic as a sibling to the current node, after it. This action opens a New file dialog box that allows you to select the type of document and assists you with naming it. After you have configured your new topic, click Create.
- Duplicate - Select this action to create a copy of the selected topic and insert it as a sibling. This action opens a dialog box that allows you to choose the file name and location for the newly created copy of the topic. After you have selected the name and path for your new topic, click OK.
  Note: The value of the root ID is generated taking the Use the file name as the value of the root ID attribute option from the DITA > Topics preferences page into account. When the option is deselected, a unique ID is generated.
Step Result: The new topic is now referenced (as a <topicref>) in the DITA map at the location where you inserted it and the new topic is opened in the editor.
Save the DITA map.

Adding Multiple Skeleton Topics at Once

Oxygen XML Author Eclipse plugin includes a feature in the DITA Maps Manager that allows you to quickly create multiple skeleton topics at once and you can specify their hierarchical structure within the DITA map.

To access this feature, right-click a node in the DITA Maps Manager where you want the new topics to be inserted and select Fast Create Topics. This opens the Fast Create Topics dialog box where you can configure the structure for the new topics.

For more information, see Fast Create Multiple DITA Topics.

Adding Multiple References to the Same Topic in a Map

Oxygen XML Author Eclipse plugin allows you to reuse entire topics by adding multiple references to the same topic in a DITA map. Whenever multiple references to the same topic are detected in the context of the current map in the DITA Maps Manager, an indicator will appear in the top-right corner of the Author mode editor that shows the number of times the topic is referenced in the DITA map. It also includes navigation arrows that allow you to jump to the next or previous reference.

Remove Topics from a Map

You can remove topics from a map in a number of ways. Some ways to remove a topic from a map include:

Highlight the topic and press the Delete key on your keyboard.
Highlight the topic and click the Delete button on the DITA Maps Manager extended toolbar.