Webhelp and DITA Maps

Post here questions and problems related to editing and publishing DITA content.
Jeff_Reynolds
Posts: 20
Joined: Tue Apr 13, 2021 9:48 pm

Webhelp and DITA Maps

Post by 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
Posts: 88
Joined: Mon Jun 12, 2017 10:50 am

Re: Webhelp and DITA Maps

Post by 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).
Regards,
Cosmin
--
Cosmin Andrei
oXygen XML Editor and Author Support
chrispitude
Posts: 470
Joined: Thu May 02, 2019 2:32 pm

Re: Webhelp and DITA Maps

Post by 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
webhelp_1.png (75.54 KiB) Viewed 153 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
webhelp_2.png (14.84 KiB) Viewed 153 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 7 times
Jeff_Reynolds
Posts: 20
Joined: Tue Apr 13, 2021 9:48 pm

Re: Webhelp and DITA Maps

Post by Jeff_Reynolds »

Thanks for this fantastic answer!
Post Reply