Advanced operations

Inserting a Topic Reference

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.

Figure 6.2. Insert Topic Reference Dialog

Insert Topic Reference Dialog

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. You can also select multiple resources in the file explorer and then insert them all as topic references.

Another easy way to insert a topic reference is to directly drag and drop topic files from the Oxygen Project or the Explorer right in the DITA Maps tree.

You can also define keys using the Keys text field on the inserted topicref or keydef element or instead of using the Href to point to a location you can reference a key definition using the Keyref text field.