Edit online

Block-Level Comments

Oxygen Feedback includes a dynamic feature that allows your users to add and manage comments contextually at a specific location within the output page where block elements appear (e.g. section, paragraph, list, or table elements) without having to scroll to the comments area at bottom of the page. This means that the feedback is more precise and it is easier to locate the exact content referenced in the comments. The block-level comments are also displayed in the comments area at the bottom of the page, aggregated along with all the comments added in that area. The block-level comments in the bottom area are marked with a specific status badge (). If you click that badge, the page scrolls to the context element associated with the block-level comment.

For information about how commenters can add or manage block-level comments, see the Commenter Guide: Adding a Comment.

How Comments are Associated with Block-Level Elements

From a technical standpoint, Oxygen Feedback uses a special attribute (data-ofbid="topicID/elementID") to associate a comment with an HTML element. For any element that has the data-ofbid set, a comment widget () is generated on the ride side of the content when a user hovers over content within the block (content inside a block element in the source document). The user can click the comment widget to add a comment it that particular location within the page. Once comments exist within a block, a widget is displayed with the number of comments that exist within that particular block shown in a red circle ( ). Users and admins can click that widget to manage existing comments.

The data-ofbid attribute is automatically generated in the output for DITA elements that have an ID attribute set in the source content. The automatically generated value for the data-ofbid attribute is stored in the database and Oxygen Feedback uses the generated value to create a mapping between the element in the output and the element in the source document. Therefore, it is important to maintain the IDs in the source documents to ensure that this mapping persists.
Note: If you do not want to add IDs to the block elements in the DITA source files but you still want your users have access to the block-level comments feature, you can set the webhelp.enable.block.elements.id.generation transformation parameter to yes. This results in the data-ofbid attribute being automatically generated for block elements that do not have an ID in the source. A potential drawback to this is that if block-level comments are added in the output after the data-ofbid attribute is generated for elements that do not have an ID in the source and then the output is regenerated, the mapping between the block-level comment and the element will be lost and the orphaned comment will be displayed in the commenting component at the bottom of the page with a warning symbol in their status badge () to make them easily identifiable.

How to Automatically Generate IDs in Oxygen XML Editor/Author

If your source content is maintained in Oxygen XML Editor/Author, there are several convenient methods for automatically generating IDs:
  • If you right-click a map in the DITA Maps Manager and select Refactoring > Generate IDs, a wizard will be presented where you can select which elements will have an ID automatically generated (and you can specify a value pattern).
  • To have IDs automatically generated for specific elements as you edit documents going forward, go to DITA > ID Options. This opens a dialog box where you can select which elements will have an ID automatically generated (and you can specify a value pattern). Make sure you select the Auto generate IDs for elements option for the feature to work automatically going forward

Resources

To see a visual demonstration of the block-level comments feature, watch our video: