`<mapref>`

A map reference is a mechanism for referencing a DITA map from a DITA map.

Usage information

The <mapref> element is a convenience element. It is equivalent to a <topicref> element with the @format attribute set to ditamap.

Processing expectations

The hierarchy of the referenced map is merged into the container map at the position of the reference, and the relationship tables of the child map are added to the parent map.

Specialization hierarchy

The <mapref> element is specialized from <topicref>. It is defined in the mapgroup-domain module.

Attributes

The following attributes are available on this element: common map attributes, link-relationship attributes, universal attributes, @impose-role, @keyref, and @keys.

For this element:

The @format attribute has a default value of ditamap.
The @impose-role attribute has a fixed value of keeptarget.

Example

The following code sample shows how a <mapref> element can be used to reference a submap. The base-elements.ditamap document references the map-group-elements.ditamap):

<map>
 <title>Base elements</title>
 <!-- ... -->
 <topicref href="containers/domain-elements.dita" >
  <!-- ... -->
  <mapref href="map-group-elements.ditamap"/>
  <!-- ... -->
 </topicref>
 <!-- ... -->
</map>

The map-group-elements.ditamap document contains references to the element-reference topics for the map group domain. It is constructed as a map in order to enable easy editing of the child topics.

<map>
 <title>Map group elements</title>
 <topicref keyref="mapgroup-d" >
  <topicref keyref="keydef" />
  <topicref keyref="mapref" />
  <topicref keyref="topicgroup" />
  <topicref keyref="topichead" />
 </topicref>
</map>

After processing, the base-elements.ditamap contains the topic references that originally were located in the submap:

<map>
 <title>Base elements</title>
 <!-- ... -->
 <topicref href="containers/domain-elements.dita" >
  <!-- ... -->
  <topicref keyref="mapgroup-d" >
    <topicref keyref="keydef" />
    <topicref keyref="mapref" />
    <topicref keyref="topicgroup" />
    <topicref keyref="topichead" />
  </topicref>
  <!-- ... -->
 </topicref>
 <!-- ... -->
</map>