Webhelp and DITA Maps

[Jeff_Reynolds]

I there a description of how DITAMAPs can be presented in tiled webhelp? How does nesting topics or maps by reference change navigation?

Thanks!

[cosmin_andrei]

Hi Jeff,

Could you please provide us more details about your use-case and what would you like to achieve?
Also, in order to investigate this, we would appreciate if you could send us a sample file for which the issue is reproducible (using either the online support form or the official support email - support@oxygenxml.com).

[chrispitude]

Hi Jeff,

The basic rules are:

• The DITA navigation hierarchy is used for the WebHelp structure.
• DITA topic references contribute to navigation hierarchy.
• DITA map references do not contribute to navigation hierarchy, unless they are contained in a <topichead> element (whose purpose is to contribute navigation hierarchy at the map level).

For example, consider the following:

webhelp_1.png (75.54 KiB) Viewed 734 times

Note that the books A and B use a bare <mapref>, while books C and D use a <mapref> in a <topichead>. The WebHelp presentation is as follows:

webhelp_2.png (14.84 KiB) Viewed 734 times

Notice that for books C and D, the tile text comes from the navigation title and not the book title! Essentially, map references are "transparent" containers for their content.

When you click on a tile, the content presented comes from whatever navigation structure exists under that tile's level.

You can also use <topichead> to group multiple items together:

Code: Select all

<topichead>
    <topicmeta>
        <navtitle>Collection With Books C and D</navtitle>
    </topicmeta>

    <topichead>
        <topicmeta>
            <navtitle>Book C</navtitle>
        </topicmeta>
        <mapref href="bookC.ditamap"/>
    </topichead>
    <topichead>
        <topicmeta>
            <navtitle>Book D</navtitle>
        </topicmeta>
        <mapref href="bookD.ditamap"/>
    </topichead>
</topichead>

There is some related discussion here that helps explain things:

https://dita-users.groups.io/g/main/top ... 6138#46795

including a reference to a DITA-OT plugin I use that enhances map references to contribute their own navigation hierarchy, avoiding the need to manually add <topichead> structure and hardcode title text.

Here is my WebHelp testcase, if you want to experiment with it:

webhelp_structure.zip

(12.5 KiB) Downloaded 120 times

[Jeff_Reynolds]

Thanks for this fantastic answer!