Tracking in WebHelp TOC

[MichaelDa]

Hi.

I recently upgraded from Oxygen Author 13.2 to 14.2, and there appears to be a new feature in WebHelp TOC where, when the user clicks a link, the TOC opens to that topic.

This is fine when all topics in the ditamap are unique. However, when there are multiple instances of a topic in the ditamap, the user is taken to the first instance of the topic in the TOC, which may not be the topic they need.

Since upgrading, this has been the primary complaint about the new WebHelp format. Our users like the new look and feel, but they do not like this feature because it inhibits the usability of the documentation. Is there any way to turn this feature off?

You can look at one of our documents as an example:

1. Go to the document: http://documentation.agilepoint.com/Sup ... index.html

2. In the TOC, navigate to AgilePoint BPMS v5.0 SP3 > Sorted by Component > 01 Envision > 01.0089

Expected Behavior: The user can click through the "Sorted by Component" list to see all the fixes in numerical/chronological order for the 01 Envision component.

Observed Behavior: The TOC jumps to the "Sorted by Date Added" list for all components.

[sorin_ristache]

Hi,

This is fine when all topics in the ditamap are unique. However, when there are multiple instances of a topic in the ditamap, the user is taken to the first instance of the topic in the TOC, which may not be the topic they need.

Since upgrading, this has been the primary complaint about the new WebHelp format. Our users like the new look and feel, but they do not like this feature because it inhibits the usability of the documentation. Is there any way to turn this feature off?

When a new topic is opened in the right side frame the first reference to that topic is highlighted in the left side frame (the Content frame) which in the case of multiple references in the map may not be the correct one. That is a limitation of the JavaScript code that highlights the topic references in the Content frame. In your case (opening a topic by a direct link from the Content pane) this behavior is obviously a bug, however when the topic is opened by clicking on a link in other topic the problem cannot be resolved because there is not enough data to determine which reference (from the set of multiple identical references) should be highlighted in the Content frame.

This feature cannot be disabled, however there is a very simple workaround (which seems to fit in the overall DITA philosophy) for highlighting only the correct reference in the Content frame: differentiate the multiple references to the same topic in the same map by adding a copy-to parameter to the second, third, etc. reference, for example:

Code: Select all

  <topicref href="topic.dita"/>

  . . .

  <topicref href="topic.dita" copy-to="topic-second.dita"/>

  . . .

  <topicref href="topic.dita" copy-to="topic-third.dita"/>

Regards,
Sorin

[MichaelDa]

Hi Sorin.

The issue is backward compatibility. We should not need to make major changes to our source files or document design because you add a new feature to your product. There should be a way to disable it or make it optional.

Is there a way to disable the JavaScript that tracks/highlights the first topic in the TOC?

Thanks,
Michael

[sorin_ristache]

Hi Michael,

You can disable the feature that selects the current topic in the Content pane in the left side of the browser window by commenting out the 2 lines from the file [Oxygen-14.2-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\oxygen-webhelp\resources\js\tocWDiv.js that contain the string addClass('menuItemSelected'), that is lines 433 and 823. This is for the internal frames version of the Webhelp output (the index.html main output file). If you prefer the frameset version (the index_frames.html output file) which is also created by the same Webhelp transformation, then you have to comment out the lines containing the same string (that is addClass('menuItemSelected')) but from the file [Oxygen-14.2-install-dir]\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\oxygen-webhelp\resources\js\toc.js, which means lines 246 and 334.


Regards,
Sorin

[MichaelDa]

Hi Sorin.

Your suggestion regarding tocWDiv.js resolves one part of the issue: It doesn't make the TOC item bold anymore. However, the more important issue I'm trying to resolve is not fixed: The TOC "jumps" to the first instance of the topic in the TOC.

The observed result after the fix is that when we click the link where a topic is duplicated, the TOC expands and moves to the first instance of the topic in the TOC, but the first instance is not highlighted/bold.

With this result, the user is still "lost" in the TOC when there is more than one item in sequence, but those items have duplicate topics in the TOC. (See the use case in my first post in the thread.)

What we are looking for is the behavior in 13.2: When a user clicks an item in the TOC, the TOC does not jump or move to a location other than the TOC item the user clicked on.

Thanks,
Michael

[sorin_ristache]

Hi Michael,

You are right, the Content panel should not jump to other item in the tree. We will fix this problem in the next version (15.0), maybe also in a maintenance build for version 14.2.


Regards,
Sorin

[MichaelDa]

Hi Sorin.

Great to hear you will be fixing this in the future. If this fix becomes available, or you could provide a timeline, we would appreciate an update.

Thank you,
Michael

[sorin_ristache]

Hi Michael,

Of course we will update this forum topic when we have fixed the Content panel jump problem, hopefully by Oxygen release 15.0 which will probably be in June this year.


Regards,
Sorin

[MichaelDa]

Hi Sorin.

I'm not sure what you mean by the Content panel. I sent a video to the Oxygen Support email with a detailed description of our issue, but I haven't heard a response. Will the issue in that video be addressed?

Thanks,
Michaei

[sorin_ristache]

Hi Michael,

It is exactly the issue that you show in the video which you sent, the issue with jumping to the same topic but linked from a different section of the table of contents. The table of contents is located in a panel in the left side frame of the browser window, and this panel has the title Content (the left side frame contains two panels: Content and Search).


Regards,
Sorin

[MichaelDa]

Excellent! Thanks Sorin.