Skriftlig Info ➜ DITA publishing ➜ DITA maps ➜ Inserting a topic map into a bookmap

Inserting a topic map into a bookmap

When you have made a new topic map you can insert into a bookmap.

(This procedure is based on the Tridion Docs database repository and Oxygen XML editor. Other tools have similar functionality.)

Prerequisites

You have all the tools available, and the relevant access rights to develop new content. The bookmap is checked out in your editor.

Context

A topic map can be inserted into a bookmap in only one way. It must be placed inside a <chapter> element.

<bookmap>
...
<chapter href="Stem topic">
   <mapref href="Topic map 1"></mapref>
</chapter>
...
</bookmap>

There are no limitations on how many topic maps you place inside the <chapter> element.

<bookmap>
...
<chapter href="Stem topic">
   <mapref href="Topic map 1"></mapref>
   <mapref href="Topic map 2"></mapref>
</chapter>
...
</bookmap>

In many cases, the <chapter> will contain a topic with only a title. These topics with only a title are referred to as stem topics.

There are two ways to insert the topic map:

• You can use the editor's dialogue box
• You can manually insert a <mapref> element and then copy the map's GUID into the href attribute.

Procedure

1. Using the editor's dialogue box:

   1. Place the cursor inside the <chapter> element where you want to insert the topic map.

   2. From the editor's main menu, select DITA ➜ Insert topic reference.

   3. In the dialogue box that opens, set Reference type to Map Reference.

   4. On the right side of the dialog, click the green icon to open the database.

   5. In the database, locate the map you want to insert.

   6. Once you find it, double-click it to select it.

      The dialogue box reopens.

   7. Click Insert and close.

2. Inserting a <mapref> element manually:

   1. Find the map you want to insert, and copy the GUID identifier for it.

      You can retrieve the GUID identifier from the map's Properties dialog. If you've put the GUID identifier in a comment at the top of the map, you can retrieve it from a preview. You can also open the map to have a look.

   2. Place the cursor inside the <chapter> element where you want to insert the map.

   3. Press the Enter key on your keyboard and select <mapref> from the shortcut menu.

   4. Click the start tag in the <mapref> element, then press Alt-Enter on your keyboard to open the attributes dialogue box.

      

   5. Set name to href.
   6. Copy the GUID identifier into the Value box.
   7. Click OK.

3. Note that the <mapref> element now appears in your <chapter> element with the maps's GUID identifier shown.

4. Recommended: Do the following:

   1. Click the small icon that appears on the left side of the <mapref> element.

      The map opens in the editor.

      Verify that you have inserted the correct map.

   2. Copy the two comments you entered when you created the map, and paste them above the <mapref> element in the topic map.

   Like this:

   <comment>The topic's metadata title</comment>
   <comment>The topic's GUID identifier</comment>
   <mapref href="GUID">(The topic's GUID identifier is shown here)</mapref>
   

   The comments will always tell you which map you have inserted. If you need to copy the <mapref> element to another location, remember to include the two comments.

Related texts

About DITA maps

DITA bookmap

DITA bookmap structure

DITA topic maps

Relationship tables

Building structure in a bookmap

Building structure in a topic map

Make "small" bookmaps

Use topic maps with embedded stem topics

Create topic maps that you can reuse in the relationship tables

---

All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.

The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.