Element-Level Comments

Element-level comments are those that can be applied to specific HTML elements. With element-level comments, users can click specific content to comment on it. This is best applied to XML-based content. These are enabled on content by adding

<#include
            "components/comments/elementLevelComments.ftl"/>

to any content-displaying page.

The entire template is wrapped in <#if user?? && portal.hasFeature('elLevelComments')>. This will ensure that element-level comments are only enabled if a user is logged in and the portal has the element-level comments feature enabled. Note that this is subtly different from document-level comments, which require security to be configured but do not require that a user be logged in.

The portal establishes two variables, annotationCandidates and annotationExceptions, which are used to select the annotatable elements. The value passed to annotationCandidates is '[data-xtrc]'. This will select all elements that have a data-xtrc attribute. Titania Delivery places these attributes on all elements that correspond to a source DITA element. Because element-level commenting works best on block-level elements, a list of inline HTML tags (and some others) are passed to annotationExceptions, removing them as annotation candidates. This list can be safely customized and experimented with.

Note: The Titania Annotator plugin will "filter" annotatable elements to prevent nesting. An annotable element nested in another annotable element confuses the UI, and makes it difficult to determine which element the comment was intended for. Therefore, if the plugin detects nested annotatable elements, it will only allow commenting on the parent element.

To enable element-level commenting, Titania Delivery activates the Comment Manager via the following:

$('#viewerContent').find(annotationCandidates).not(annotationExceptions).titaniaAnnotate({
  serverUrl: HARPPortal.getPortalRpcUrl('comments'),
  siteKey:'${portal.commentManagerSiteKey?js_string}',
  pageId: 'elements:${itemData.item.projectKey?js_string}${itemData.item.projectPath?js_string}::${itemData.item.lastModified?datetime?iso_utc?js_string}',
  author: {
    name: '${user.userName?js_string}',
    id: '${user.id?js_string}'
  },
  targetId: function($el) {
    var xtrf = $el.closest('[data-xtrf]').attr('data-xtrf'),
        xtrc = $el.attr('data-xtrc');
    
    return xtrf && xtrc ? xtrf + '#' + xtrc : null;
  },
  metadata: function($element) {
    return {
      xtrf: $element.closest('[data-xtrf]').attr('data-xtrf'),
      xtrc: $element.closest('[data-xtrc]').attr('data-xtrc'),
      itemKey: '${itemData.item.key?js_string}',
      itemName: '${itemData.item.label?js_string}',
      projectKey: '${itemData.item.projectKey?js_string}',
      portalName: '${portal.name?js_string}',
      portalKey: '${portal.key?js_string}',
      <#if contextMetadata??>
        contextKey : '${contextMetadata.key}',
        contextName: '${contextMetadata.name}',
      </#if>
      modifiedDate: '${itemData.item.lastModified?datetime?iso_utc?js_string}'
    };
  },
  moderators: [<#list moderators as m>'${m?js_string}',</#list>]
});

It is not recommended that any of the above values be changed. However, any of the other options available to the Titania Annotator may be customized.