Maps

Maps enable you to create deliverables by adding references to topics or other maps.

Create a Map

Maps enable you to build deliverables.
  1. In the content library, navigate to a folder and click Create New.
  2. Select the map type you want to create.
  3. Enter a title and file name.
  4. Optional: Create the file in a folder different from the current folder by clicking Change and selecting a new location.
  5. Optional: Assign the file to collections by clicking Collections and selecting collections from the list.
  6. Optional: Assign metadata to the file by filling in the Metadata fields.
  7. Do one of the following:
    • To create and open the file, click Create & Edit .
    • To create the file and return to the content library, click Create .

Create a Multilingual Map

Creating a multilingual map enables you to publish a multilingual deliverable.

  • Localize your content.
  • Create a map that you will use as a multilingual map. See Create a Map.
  1. In the content library, open the multilingual map in the map editor by clicking the Dock button.
  2. In the content library, navigate to the localized map or topic.
  3. Add the localized map or topic to the multilingual map by doing the following:
    1. Drag and drop the localized map or topic into the map editor.
      Figure 1. Dragging and Dropping Resources
      Figure 2. Insert Dialog
    2. Click Insert.
    3. Repeat step 3 with the same localized map or topic for each language that you want to publish the resource in.
      Figure 3. Localized Resource Inserted Multiple Times
  4. Set language attributes for localized maps or topics by doing the following:
    1. Right-click the localized map or topic that you want to publish in another language and select Edit element attributes .
      Figure 4. Map Editor Context Menu
    2. In the lang field, enter the locale that you want to publish the localized map or topic in.
      If you want to publish the map or topic in Spanish used in Spain, enter es-es
      Figure 5. Spanish Locale
    3. Click Save .
    4. Repeat step 4 for every localized map or topic that you want to publish in a particular language.
You created a map for a multilingual publication.
Generate a single output with the content repeated in each language by publishing the multilingual map.
Figure 6. Table of Contents of a Multilingual Publication

Change the Map Title

You can modify the title of an existing map.

  1. In the content library, hover over a map and click the Dock button.
  2. In the map editor, click Tools > Change Title .
  3. Enter a new map title.
  4. Click Save .

Map Elements

Elements are the building blocks of a map.

Insert Existing Content to a Map

You can add existing maps and topics from your content library to a map.

  1. In the content library, hover over a map and click the Dock button.
  2. In the content library, navigate to the component(s) that you want to add to the map.
  3. If you want to add multiple components, select the components. See Select a Range of Files.
  4. Drag and drop the component(s) from the content library into the map editor.
    Tip: A line appears that indicates where the component will be added. If you drop a component on another component, a green box appears. The green box indicates that the new component will be added as a child of the component that is already in the map.
  5. If prompted, from the Insert drop-down menu, select a relevant reference type and click Insert.
    Note: Your easyDITA instance can be configured to automatically select the appropriate reference type for you. If you want to select the reference type on your own, you can hold Shift while dragging and dropping a resource into the map tree.

    To disable or enable the intelligent drag and drop feature, contact a Customer Success Manager.

Insert New Content to a Map

Add new topics or maps to a map.

  1. In the content library, hover over a map and click the Dock button.
  2. In the content library, navigate to a folder and click Create New.
  3. Drag and drop a map or topic from the Create New menu into the map editor.
    Tip: A line appears that indicates where the component will be added. If you drop a component on another component, a green box appears. The green box indicates that the new component will be added as a child of the component that is already in the map.
    Figure 7. Dragging and Dropping
  4. If prompted, from the Insert drop-down menu, select a relevant reference type and click Insert.
    Note: Your easyDITA instance can be configured to automatically select the appropriate reference type for you. If you want to select the reference type on your own, you can hold Shift while dragging and dropping a resource into the map tree.

    To disable or enable the intelligent drag and drop feature, contact a Customer Success Manager.

  5. Enter a title and file name.
  6. Optional: Create the file in a folder different from the current folder by clicking Change and selecting a new location.
  7. Optional: Assign the file to collections by clicking Collections and selecting collections from the list.
  8. Optional: Assign metadata to the file by filling in the Metadata fields.
  9. Do one of the following:
    • To create and open the file, click Create & Edit .
    • To create the file and return to the content library, click Create .

Add an Element to a Map

You can add elements to the map by using the map editor or topic editor.

  1. Open a map by doing one of the following:
    • To open a map in the map editor, in the content library, hover over a map and click the Dock button.
    • To open a map in the topic editor, in the content library, hover over a map and click the Open button.
  2. In the pane on the left, right-click an element.
  3. Add an element to the map by doing one of the following:
    Note: Depending on the type of map that you edit and your location in the map, the available elements may vary.
    • Hover over Append element and select the element you want to add as a child of the selected element.
    • Hover over Insert element before and select the element you want to insert before the selected element.
    • Hover over Insert element after and select the element you want to insert after the selected element.

Move an Element in a Map

Organize topics and other elements in a map in the way that you want them to appear in the final output.

  1. Open a map by doing one of the following:
    • To open a map in the map editor, in the content library, hover over a map and click the Dock button.
    • To open a map in the topic editor, in the content library, hover over a map and click the Open button.
  2. In the pane on the left, do one of the following:
    • To move the topic as a peer, drag and drop the topic above or below another peer topic.
      Tip: A line indicates where the component will be added.
    • To make the topic a child, drag and drop the topic on top of another topic.
      Tip: A green box shows around the topic to indicate that the topic will be a parent topic.

Remove an Element from a Map

Remove unwanted content from a map by using the map editor or topic editor.

CAUTION: If you remove an item, you also remove all the references to its children. If the links to children need to be preserved, move them to another location in the map before you delete the parent. For example, if you have a topic hierarchy in the map and remove the parent topic, the parent's children topics will also be removed.
  1. Open a map by doing one of the following:
    • To open a map in the map editor, in the content library, hover over a map and click the Dock button.
    • To open a map in the topic editor, in the content library, hover over a map and click the Open button.
  2. In the pane on the left, right-click the element you want to remove and select Remove element .

Navigational Headings

You need to insert navigational elements in your DITA map to display map titles in the output.

For more information, in the Technical Content Development Guide, see Maps with Map Hierarchy.

Map Without Navigational Headings

In this example, the “Master Map” (outlined in black) contains a hierarchy of submaps (outlined in blue and green). Publishing the “Master Map” generates the following navigation in PDF and WordPress outputs.

Figure 8. Navigation

The topic titles (“Topic A”, “Topic B”, “Topic C”, etc) display but the map titles (“Getting Started”, “Interface”, “Features”, “Controls”) do not. To display map titles, you need to define navigational heading elements in the map.

Map with Navigational Headings

The following examples show a map with hierarchy.

  • User Guide (master-map)
    • Topic Editor (submap)
      • Interface (topic)
      • Using the Topic Editor (topic)
    • Map Editor (submap)
      • Interface (topic)
      • Using the Map Editor (topic)

The following example shows the source code for a map with navigational headings for each submap:

Figure 9. Map with Navigational Headings
<map id="_m_user_guide" title="User Guide">
	<title>User Guide</title>

	<topichead>
		<topicmeta>
			<navtitle>Topic Editor</navtitle>
		</topicmeta>
		<mapref href="_m_topic_editor.ditamap" />
	</topichead>

	<topichead>
		<topicmeta>
			<navtitle>Map Editor</navtitle>
		</topicmeta>
		<mapref href="_m_map_editor.ditamap" />
	</topichead>

</map>

Create a Navigational Heading

Insert navigational elements in your DITA map to display map titles in the output.

  1. Open a map by doing one of the following:
    • To open a map in the map editor, in the content library, hover over a map and click the Dock button.
    • To open a map in the topic editor, in the content library, hover over a map and click the Open button.
  2. Right-click the map element, and select Append element > Empty > topichead.
  3. Hover over the topichead element and click the wrench button.
  4. Fill in the Navtitle field with the title of your navigational heading.
  5. Drag a map from the content library or the pane on the left and drop it onto the topichead element.
  6. If a dialog appears, select mapref element and click Insert.
Figure 10. Navigational Heading.

The map is added as a child of the topichead element.

Map Elements Attributes

Assigning attributes enables you to manage the properties of elements in a map.

For detailed information on the DITA attributes, see DITA 1.3 Specification.

Edit Map Element Attributes

Edit the attributes of an element in a map to manage its properties.

  1. Open a map by doing one of the following:
    • To open a map in the map editor, in the content library, hover over a map and click the Dock button.
    • To open a map in the topic editor, in the content library, hover over a map and click the Open button.
  2. In the left pane, hover-over a map element and click the wrench button.
  3. In the pop-up, do any of the following:
    • To change the element type, from the Element drop-down list, select a different option.
    • To assign, modify, or remove an attribute, in the Attributes section, edit the attribute field.
    • To edit the element in the source editor, click the pencil button.

      For more information, see Source Editor.

Chunk Attribute

Chunk content to control how topics appear on a page when published. The chunking attribute is commonly used as a way to identify to the end-user that some content is a unit of information.

When you specify a chunking attribute, it overrides the default chunking behavior, which is to show each topic on its own page. For example, if you have a parent topic with several children, you can use the chunking attribute to specify if the topics appear on a single page or separate pages when publishing to HTML.

Here's an example map with some hierarchy:

When you publish this map with no chunking attribute applied, the parent topic shows on the page with links to each of the children topics. The following HTML example highlights this behavior.

When you publish this map with the to-content chunking attribute, the parent topic and each of it's children show on the same page. The following PDF example highlights this behavior.

You can apply a chunk attribute to a single topic or to a map. When you apply a chunk attribute to a topic, the chunking behavior applies only to the topic and any children of that topic. When you apply a chunk attribute to a map, the chunking behavior is established for the entire map.

Here are the chunk attributes in DITA:

AttributeBehavior
by-topic Produces a separate output chunk for the target topic and each of its descendants.
by-document Produces a single output chunk for the referenced document.
select-topic Selects an individual topic.
select-document Selects the topic and any other topics in the document.
select-branch Selects an individual topic and any nested topics.
to-content Generates a single document containing an individual topic and any nested topics.
to-navigation Generates a new chunk of navigation, such as a Table of Contents.

Collection-Type Attribute

Use a collection-type attribute to define the type of hierarchical relationship parent and children topics have to one another and to determine the way content and related links display when published. The collection-type attribute can be applied to topics or submaps in a map to control the linking behavior between child topics and how the structure of the output displays.
Collection Type Description
Unordered Links generate from parents to children and from children to parents.
Family Links generate from parents to children, from children to parents, and from sibling to sibling. Parent topic shows on a different page than children topics.
Sequence Links generate from parents to children and from sibling to sibling in sequential order. Parent topic shows on a different page than children topics.
Choice Links generate from parents to children and from children to parents, but where one child topic is selected to proceed.

Unordered Collection Type

If you're documenting unrelated items that don't follow a specific order, use an unordered collection type. For example, each topic is about a different aspect of a software that is unrelated to the others. In this map, Classic Software is the parent topic and the other topics are children of Classic Software:

When published the parent topic contains links to each of the children topics:

Each of the children contains a link to the parent topic, but not to one another:

Family Collection Type

In a family collection type, all items are related to one another. For example, you have a map discussing troubleshooting strategies for a printer. In this map, Printer Troubleshooting is the parent topic and each of the strategies are children of that parent topic:

When published, the parent topic contains links to each of the children topics:

Each of the children topics contains links to the parent topic and all related topics:

Sequence Collection Type

A sequence collection type is good for information that must be presented in a specific order. For example, you have a series of software installation tasks that need to be completed in order. In this map, Classic Software is the parent topic and each of the procedure topics are children of that parent topic:

When published, the parent topic contains numbered links to each of the children topics:

Each of the children topics contains links to the parent topic and to the previous and next topics in sequence:

Choice Collection Type

A choice collection type is good for information that requires you to choose from two or more options. For example, you are creating a new file in Classic Software and have the option to choose from a blank file, default template, or uploaded template. In this map, Creating a New File is the parent topic and each of the options for creating a file are children of that parent topic:

When published, the parent map contains links to each of the children topics:

Each of the children topics contains links to the parent topic, but not to one another:

Map XML Code

easyDITA enables you to edit the source code of your maps.

Edit the Map XML Code

You can open a map in the source editor directly from the content library or by using the map editor or topic editor.

Important: If multiple users collaborate on a resource, easyDITA places a collaboration lock on the topic and the XML code is not editable.
  1. Open a map in the source editor by doing any of the following:
    OptionDescription
    To open the source editor directly from the content library, in the content library, right- click a map and select Open in Source Editor .
    To open the source editor from the map editor, do the following:
    1. In the content library, hover over a map and click the Dock button.
    2. In the map editor pane, right-click the map and select Edit Element XML .
    To open the source editor from the topic editor, do the following:
    1. In the content library, hover over a map and click the Open icon or double-click a map.
    2. In the left pane, right-click the map name and select Edit Element XML .
    Tip: You can edit the XML code of a map element, for example, a chapter with its child topics, by right-clicking the element and selecting Edit Element XML .
  2. Optional: Expand or collapse elements by clicking the corresponding Plus icons or Minus icons.
    Tip: Collapsing irrelevant elements increases readability and limits distractions.
  3. Edit the XML code.
    Tip: The gray line in the scroll bar indicates your cursor position.
  4. Optional: Make your code more readable by clicking the Format the source icon.
  5. Click Save .
  6. If the Failed to Save Document window appears, click OK and fix the invalid XML code by repeating 3 through 5.

Find and Replace the Map XML Code

You can find and replace the XML code of a map in the source editor.

Important: If multiple users collaborate on a resource, easyDITA places a collaboration lock on the topic and the XML code is not editable.
  1. In the content library, right-click a map and select Open in Source Editor .
  2. Press Cmd > F (Mac) or Ctrl > F (Windows).
  3. Search for a term by doing the following:
    1. In the Find field, type in a search term and press Enter.
      Search for <metadata>
      All search results are highlighted.
    2. Optional: Restrict the search to match case by clicking the Match Case icon.
    3. Optional: Restrict the search to match whole words only by clicking the Match Whole Word icon.
    4. Optional: Enable regular expression in the search by clicking the Use Regular Expression icon.
    5. Optional: Restrict the search scope by highlighting the document area that you want to include in the search results, and click the Find in selection icon.
  4. If you want to navigate the search results, do any of the following:
    • To navigate to the next result, click the Next match icon.
    • To navigate to the previous result, click the Previous match button.
  5. If you want to replace your search results, do the following:
    1. In the Find dialog, click the Toggle Replace mode icon.
      The Find dialog dialog expands to the Find and Replace dialog.
    2. In the Replace field, type in a term that would replace the search results.
    3. To replace the selected search result, click Replace icon.
    4. To replace all search results, click Replace All icon.
  6. Save the file by doing any of the following:
    • If you edit a topic, to save the changes and leave the Edit Source window open, click Save .
    • If you edit a topic, to save the file and close the Edit Source window, click Save & Close .
    • If you edit a map, save changes by clicking Save .
  7. If the Source XML Invalid window appears, do any of the following:
    Important: The Source XML Invalid window appears if easyDITA detects that something is wrong with the XML code that you edited. We recommend fixing the invalid XML files immediately because they may result in severe publishing errors. The Invalid XML code is indicated by a red underline and a red rectangle in the scroll bar.
    Figure 11. Invalid Code Indicators in the Source Editor

    If you plan to fix the invalid XML code later and you don't want to lose your changes, you can save the invalid XML code. easyDITA notifies you about invalid XML files by displaying the Invalid File icon in the content library.

    Figure 12. Invalid XML File in the Content Library
    • To save the invalid XML code, click the OK button.
    • To edit the invalid XML code, click Cancel .