Creating 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. Click the Permanent Deletion Date field, and select when the file should be permanently deleted.
    Warning: You cannot restore permanently deleted files, their version history, or associated metadata.
  8. 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.

If you filled in the Permanent Deletion Date field, on the “Permanent Deletion Date”, the file is permanently deleted.

Warning: This action is irreversible. You cannot restore permanently deleted files.

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, double-click on the multilingual map to open it in the Content Editor.
  2. Click the Open Library button to access files in your content library.
    Figure 1. Open Library Button
    Open Library button under the map tree lets the user access the files in their Content Library.
  3. Add the localized map or topic to the multilingual map by dragging and dropping the map or topic into the map tree.
    A video showcases the drag and drop function that allows the user to easily insert component(s) into a map tree.
An example of a table of content from a publication that contains the same map twice; once in English and once in Spanish.

Change the Map Title

You can modify the title of an existing map.

  1. In the content library, navigate to your map, right-click on it and select Edit Source.
    Alternatively, if you have already opened your map, right-click on the map element in the map tree, and select Edit Element XML

    .

  2. Enter a new title within the title tag.
    Figure 2. Editing the map title
    Editing the map title tag in the Source Editor
  3. Click Save.

Add Existing Content to a Map

You can insert existing maps and topics from your content library into a map.

  1. In the content library, double-click a map to open it in the Content Editor.
  2. Click the Open Library button to access files in your content library.
    Figure 3. Open Library Button
    Open Library button under the map tree lets the user access the files in their Content Library.
  3. In the content library, navigate to the component(s) that you want to add to the map.
  4. If you want to add multiple components, select the components. See Select a Range of Files.
  5. Add the component(s) into the map tree by doing one of the following:
    • drag and drop the component(s) into the map tree.

      A video showcases how the user can drag and drop components to easily insert them into a map tree.
      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.
    • from the map context menu, choose between Append Element, Insert Element After or Insert Element Before and click From Existing File.....

  6. If prompted, from the Insert drop-down menu, select a relevant reference type and click Insert.
    When adding content to the map tree the user can select a reference type from a drop-down menu.
    Note: Your Heretto CCMS 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 into a Map

Add new topics or maps into a map.

  1. In the content library, double-click a map to open it in the Content Editor.
  2. In the Content Editor, click the Open Library button.
  3. Add a new map or topic to the map tree by doing one of the following:
    • drag and drop component(s) from the Create New menu into the map tree.

      A video showcases how the user can drag and drop a new topic into the map tree from the Create New menu.
    • from the map context menu, choose between Append Element, Insert Element After or Insert Element Before and click From New File....

  4. If prompted, from the Insert drop-down menu, select a relevant reference type and click Insert.
    When adding content to the map tree the user can select a reference type from a drop-down menu.
    Note: Your Heretto CCMS 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 context menu in the map tree.

  1. In the content library, double-click a map to open it in the Content Editor.
  2. Right-click on an element in the map to open the context menu.
  3. Do 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 choose the element you want to add as a child of the selected element.
    • Hover over Insert element before and choose the element you want to insert before the selected element.
    • Hover over Insert element after and choose 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. In the content library, double-click a map to open it in the Content Editor.
  2. 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.
      Moving elements in the map hierarchy
    • 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.
      Inserting a child element

Remove an Element from a Map

Remove unwanted content from a map.

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. In the content library, double-click a map to open it in the Content Editor.
  2. In the map tree, right-click the element you want to remove and select Remove element from the Context Menu.

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

example map with no navigational headings

In this example, the “Main Map” (outlined in green) contains a hierarchy of submaps (outlined in blue). Publishing the “Main Map” generates the following navigation in a PDF output.

Figure 4. Navigation
example PDF output of a map with no navigational headings

The topic titles (“Topic A”, “Topic B”, “Topic C”, etc) show but the map titles (“Getting Started”, “Interface”, “Features”, “Controls”) do not. To show 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 (main map)
    • Content Editor (submap)
      • Interface (topic)
      • Using the Content Editor (topic)
    • Source Editor (submap)
      • Interface (topic)
      • Using the Source Editor (topic)

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

Figure 5. Map with Navigational Headings
example map with navigational headings
<map id="ditamap-user_guide-7358">
    <title>User Guide</title>

    <topichead>
        <topicmeta>
            <navtitle> Content Editor </navtitle>
        </topicmeta>
        <mapref format="ditamap" href="content_editor.ditamap"/>
    </topichead>

    <topichead>
        <topicmeta>
            <navtitle> Source Editor </navtitle>
        </topicmeta>
        <mapref format="ditamap" href="source_editor.ditamap"/>
    </topichead>

</map>

Create a Navigational Heading

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

  1. In the content library, double-click a map to open it in the Content Editor.
  2. Right-click the map element, and select Append element > topichead from the Context Menu.
    To add a topic head element, the user needs to right-click on the map element, choose to append element and select topichead from the list.
  3. Hover over the topichead element and click the gear icon.
  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.
    Dragging and dropping a submap onto the topichead element
  6. If a dialog appears, select mapref element and click Insert.
Figure 6. Navigational Heading.

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

A submap as a child element of a 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. In the content library, double-click a map to open it in the Content Editor.
  2. Hover over an element in the map tree and click the gear icon to opens the element properties pop-up.
    Hovering over an element shows a list of icons, including the information icon which opens the properties window.
  3. In the properties pop-up, do any of the following:
    • To change the element type, select a different option from the Element drop-down menu.
      Changing the type of an element in a map
    • To assign, modify, or remove an attribute, edit the attribute field in the Attribute section.
      Editing DITA attributes of an element in a map
    • To edit the element in the Source Editor, click the pencil button.
      Editing the source code of an element in a map

      For more information, see Source Editor.

Chunk Attribute

Chunk your content to control how topics appear on a page when published.

When you specify a chunking attribute value, 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:

example map with a parent topic and two child topics

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

example PDF output of a map with a parent topic and two child topics

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

example PDF output with a parent topic and two child topics, but with the chunking attribute applied

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 TypeDescription
UnorderedLinks generate from parents to children and from children to parents.
FamilyLinks generate from parents to children, from children to parents, and from sibling to sibling. Parent topic shows on a different page than children topics.
SequenceLinks generate from parents to children and from sibling to sibling in sequential order. Parent topic shows on a different page than children topics.
ChoiceLinks 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:

example map structure with a parent topic and a few child topics

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

example PDF output of a map with a parent topic and a few child topics

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

automatically-generated link added with the collection-type attribute set to "unordered"

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:

example map structure with a parent topic and a few child topics

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

Automatically-generated links in a parent topic added with the collection-type attribute set to "family"

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

automatically-generated links in a child topic added with the collection-type attribute set to "family"

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:

example map structure with a parent topic and a few child topics

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

automatically-generated links in a parent topic added with the collection-type attribute set to "sequence"

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

automatically-generated links in a child topic added with the collection-type attribute set to "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:

example map structure with a parent topic and a few child topics

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

automatically-generated links in a parent topic added with the collection-type attribute set to "choice"

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

automatically-generated links in a child topic added with the collection-type attribute set to "sequence"

Map XML Code

Heretto CCMS 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 Content Editor.

Important: If multiple users collaborate on a resource, Heretto CCMS 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 Edit Source.
    To open the Source Editor from the Content Editordo the following:
    1. Double-click on the map in the content library.

    2. In the Content Editor, hover over the map element in the map tree and click on the gear icon.
    3. In the Element Properties pop-up, click on the Pencil icon.Pencil icon in the Source Editor

    To open the Source Editor from the Content Editordo the following:
    1. Double-click on the map in the content library.

    2. In the Content Editor, right-click on the map element in the map tree.

    3. Choose Edit Element XML from the Context Menu.

    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.

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, Heretto CCMS 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 Edit Source.
  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 Heretto CCMS 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.

    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. Heretto CCMS notifies you about invalid XML files by displaying the Invalid File icon in the content library.

    • To save the invalid XML code, click the OK button.
    • To edit the invalid XML code, click Cancel.