Oracle Help File Formats	Contents	Previous	Next

Map File

The map file is an XML file that associates IDs with files:

The primary use of the map file is to define topic IDs and associate them with topic files. You can also associate topic IDs (and thereby the topics) with any window types defined in <wintype> elements in the helpset file. These IDs are used in the table of contents files, in index files, and in the API for context-sensitive calls.
The map file can also be used to define image IDs and associate them with image files. These image IDs can be used to display images next to tab labels (specified in <view> elements in the helpset file). They can also be used to display images next to items in the table of contents (specified in <tocitem> elements in the table of contents file).

The following table describes the elements used in the map file:

Element Description

Element	Description
`<map>`	Defines the mappings. The `<map>` element contains only `<mapID>` elements.
`<mapID>`	An ID and its associations. The `<mapID>` element has the following attributes: `target` - The ID for the associated file. Valid characters are any alphanumeric character or punctuation symbol except the equals sign (=). IDs must be unique within a helpset. However, you can assign multiple IDs to a single file. For example, you could assign one ID for a topic file to appear in one window type and a different ID for the same topic file to appear in a different window type (see the example below). `url` - The location of the file to associate with this ID (target). Relative URLs are resolved against the absolute URL for the map file. `wintype` - [optional] The name of a windows type, defined using <wintype> elements in the helpset file. If a windows type is not specified, the topic associated with this ID is displayed in the default window defined in the helpset.

<map>

Defines the mappings. The <map> element contains only <mapID> elements.

<mapID>

An ID and its associations. The <mapID> element has the following attributes:

target - The ID for the associated file. Valid characters are any alphanumeric character or punctuation symbol except the equals sign (=). IDs must be unique within a helpset. However, you can assign multiple IDs to a single file. For example, you could assign one ID for a topic file to appear in one window type and a different ID for the same topic file to appear in a different window type (see the example below).

url - The location of the file to associate with this ID (target). Relative URLs are resolved against the absolute URL for the map file.

wintype - [optional] The name of a windows type, defined using <wintype> elements in the helpset file. If a windows type is not specified, the topic associated with this ID is displayed in the default window defined in the helpset.

In the following example, the map IDs topic_1 and topic_2 are not associated with window types and therefore use the helpset's default window type. The map IDs topic_3 and topic_4 map to topic files that will be displayed in the window defined by the intro window type. Map ID topic_5.tsk will display File_5.html in the window defined by the task window type. Map ID topic_5.cncpt will display the same topic file (File_5.html) in a different window type (concept). Note also that the association between URL and wintype will be used when linking from topic to topic using URLs instead of topic IDs. For example, if a topic had a hard-coded target to File_5.html, clicking the link would display the HTML content in a task window type.


  <?xml version='1.0' ?>

  <map version="1.0">   
    <mapID target="topic_1" url="file_1.html" />   
    <mapID target="topic_2" url="file_2.html#a1" />   
    <mapID target="topic_3" url="file_3.html" wintype="intro" />   
    <mapID target="topic_4" url="file_4.html#a2" wintype="intro" />   
    <mapID target="topic_5.tsk" url="file_5.html" wintype="task" />   
    <mapID target="topic_5.cncpt" url="file_5.html" wintype="concept" />   
  </map>

This scheme allows authors to assign window types to HTML files and to also override those associations by linking to an alternate topic ID. For example, for topic-to-topic links, TOC links, index links, and hard-coded links to File_5.html, the author might use topic_5.tsk, but for links from a tutorial, the author might use topic_5.cncpt. By keeping this information in the map file, the author has one central repository for managing these assignments.