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. For information about how commenters can add or manage block-level comments, see the Commenter Guide.
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.
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.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
converted to a topic-level comment and displayed in the commenting component at the bottom
of the page. Those comments have an Out of context status badge
(
) to make them easily
identifiable.How to Automatically Generate IDs in Oxygen XML Editor/Author
- If you right-click a map in the DITA Maps Manager and select , 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 . 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
To see a visual demonstration of the block-level comments feature, watch our video: