Indicate When Topics Have Comments and/or Tracked Changes in DITA Map Viewer/Manager

[dreifsnider]

Hi Oxygen Support,

My team and our Web Author users continually ask if the DITA Maps Viewer in Web Author could visually indicate when a topic referenced in the DITA Map contains comments and/or tracked changes. The reason for this is that our Web Author users and SMEs want to be able to quickly see which topics in a DITA Map need addressing without having to open every individual topic referenced. Having some sort of visual indicator would be extremely valuable in this regard and would save many people a lot of time.

We created the following mockup to help show what we would like to see:

web-author-ditamap-view-indicators-mockup.png (448.15 KiB) Viewed 1380 times

Would this be possible to implement in the current state of Web Author or would we need to wait for a new version/SDK? We do have a Java developer on our team who would be able to implement this if it's supported.

Thank you!

Daniel

[cristi_talau]

Hello,

You can modify the DITA Map rendering by using the DITAMapNodeRendererCustomizer API. You should override the ExtensionBundle.createXMLNodeCustomizer() method in your DITA MAP framework to return an instance of DITAMapNodeRendererCustomizer. We have a sample framework that uses a custom ExtensionsBundle for DITA: https://github.com/oxygenxml-incubator/ ... ute-values . With this approach, you can only alter the name of the topic to add an emoji if it has comments.

Another option is to create your own side-view where you can list only the topics that have comments on change tracking.

The challenge with both these approaches is to determine which topics have comments and change markers. You have several options here:

• You can scan all DITA files to find Oxygen markup - this approach might have a bad performance for large projects

• Keep the mapping between topic and comments in a database that you update for each commit

Best,
Cristian

[dreifsnider]

Hi Cristian,

Thank you for your reply!

Just to confirm, it'll only be possible to alter the name of the topic to add an emoji? Would it be possible to also format the name of the topic, such as bold or italicize it?

I'll discuss this with our Java developer and respond if we have any questions.

Thanks,

Daniel

[cristi_talau]

Hello,
Yes, unfortunately, it is only possible to provide a different text to be rendered as the title of the topic. It is not possible to customize the styling.
Best,
Cristian

[dreifsnider]

Hi Cristian,

Thanks for your reply. That's unfortunate that it's not possible to stylize the topic names in the DITA Map view. Can you add this as a feature request, also with the possibility of controlling the style through CSS to make it a bit easier to manage?

(With that in mind, it would be awesome if we could add a new class to the topic reference in the DITA Map when the referenced topic contains comments/tracked changes. Then we could use CSS to add styles that target the specific class value.)

Thanks again!

Daniel

[dreifsnider]

Hi Cristian,

After talking with our Java developer, we're concerned about the possible impact scanning all DITA files could have on Web Author's performance. We've received some negative comments from some of our users about Web Author's performance and so we'd like to avoid slowing down Web Author as much as possible.

We're interested in the other method you mentioned (Keep the mapping between topic and comments in a database that you update for each commit), but the link you provided is broken. Could you provide a working one, or provide the details of this method?

Thanks,

Daniel

[jimrubin]

Hi Cristian,

Thanks for this great info.

I'm finding that the link you posted to "Keep the mapping between topic and comm ... ch commit" is broken
Could you provide the link to that page. It will be very helpful.

thanks much!

Jim

[cristi_talau]

Hello,
Sorry for the formatting problem. That phrase was not intended to be a link in the first place. I fixed it.
The solution outline is like this:

• Register a webhook in GitHub - https://docs.github.com/en/webhooks

• Create a web server that receives these webooks, deternimes the changed files and updates a database which records if a particular topic contains change tracking markup - https://www.oxygenxml.com/doc/versions/ ... ormat.html .

• When the DITA Map is loaded (in the DITAMapNodeRendererCustomizer), query the web server about which topics have change tracking markup.

Best,
Cristian

[jimrubin]

Thanks Cristian! This looks like a great design and we are looking to implement it.

[jimrubin]

Hi Cristian,

We're looking to reduce the DITA Map loading time with the above design by calling the database only once for each DITA Map loading. Is there a way to create a global variable that would be accessible by the plugin each time it creates the topic name? We would call the database once when the DITA Map begins loading and query all change/comment metadata for the repository. Then, the plugin would look in the global variable for info on the particular topic name it's creating. Is there anything in the API that would allow us to do this?

thanks,

Jim

[cristi_talau]

Hello,

The DITAMapNodeRendererCustomizer is cached for several minutes. So you can store all the titles in a field of your subclass of DITAMapNodeRendererCustomizer.

Alternatively, you can just use a static variable where you keep a mapping from the topic URL to the topic title. You can use the base URL (getXMLBaseURL()) of the AuthorNode as a cache key (if you have maprefs, use the base URL of the root node).

Best,
Cristian

[cosminef]

Hello,

Here [1] you can find a sample framework that customize rendering of the DITA Map nodes by installing a custom DITAMapNodeRendererCustomizer [2] that appends to each topicref its href.

[1] https://github.com/oxygenxml-incubator/ ... enderering
[2] https://www.oxygenxml.com/InstData/Edit ... mizer.html

Best,
Cosmin

[jimrubin]

Is there a way to delete the DITAMapNodeRendererCustomizer cache when we need that? We have a use case where this will be important. When a user is going through a list of topics they are updating or commenting on, when they then commit that file, it would be very helpful if the badge associated with that topic updated. Right now, it takes about 10 minutes before information registered in our database shows up in the ditamap. I'm assuming this is related to the timeout on the DITAMapNodeRendererCustomizer cache. Is there an action we can call and then attach to a button that the user could select so that the DITAMapNodeRendererCustomizer runs and pulls fresh badging data from our database?

[cosminef]

Hello,

Thank you for your interest in our products.
Currently, this is not possible.
We have logged a feature request (WA-7529) to expose an API that allows refreshing or updating titles in the DITA Map side-view.
When this feature becomes available, we will notify you here on the forum.

Best,
Cosmin