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.
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
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 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
Resources
To see a visual demonstration of the block-level comments feature, watch our video: