Comment Management with the Titania Annotator Plugin

Commenting in a Titania Delivery Portal is managed by a plugin to the jQuery JavaScript library called TitaniaAnnotator.js. This plugin is highly configurable and meant to provide a venue to receive information back from Portal users.

You can enable commenting on any element in a page by calling $(<selector>).titaniaAnnotate(). Replace <selector> with a CSS selector, identifying the element or elements on the page on which to allow commenting. The titaniaAnnotate() function accepts as an argument either an object with the fields listed below, or a String with the single legal value of off which turns off commenting.

The following code snippet should be included in the <head> element of every page that uses this library. The first and third lines are required. The middle line is optional, but provides for nicer time formatting on comments than would exist without it.

<link rel="stylesheet" href="<@c.url value="/resources/cm/cm.css"/>"></link>
<script type="text/javascript" src="<@c.url value="/resources/scripts/libs/moment.min.js"/>"></script>
<script type="text/javascript" src="${cmScriptLocation}"></script>

serverUrl

Type: String
Required: Yes
Default: None

The server endpoint that handles the persistence of the comments.

siteKey

Type: String
Required: Yes
Default: None

The key that associates comments to a particular site.

pageId

Type: String
Required: No
Default: The URL of the current page

A unique identifier that associates a comment with a given page. This allows for retrieving all the comments on a given page with a single call.

author

Type: Object
Required: Yes, unless readOnly is set to true
Default: {name: 'Anonymous', id: ''}

The name and id of the currently logged-in user. If the readOnly option is set to true, then this field may be ommitted. Otherwise, a valid user must be passed in.

targetId

Type: String or function
Required: false
Default: 'id'

If the value of this option is a String, then it must be the attribute on the element selected for commenting whose value uniquely identifies that element as the target of that comment. By default, this is the id attribute of the element.

If the value of this option is a function, then it must return a string that uniquely identifies the element being commented upon. This is useful if the unique identifier is the combined values of more than one attribute.

If this value is changed after comments have been left, those comments will no longer be associated with the element unless it is later changed back to its original value. Once this value has been determined, it is a good idea to leave it as-is.

metadata

Type: Object or function(jQuery $element)
Required: No
Default: None

The metadata field can be used to store additional arbitrary data on the comment. Each field name must be unique within the metadata object, and each value must be a String. If the value of the metadata field is a function, it must return an object. The element being commented on is passed in via $element

Moderators

Type: Array
Required: No
Default: []

The moderators array contains the user IDs that have moderator privileges. Each ID must be a String. A moderator can view, edit, and delete any comment.

showLoadingIndicator

Type: boolean
Required: No
Default: true

Comments are loaded asynchronously, after the page has loaded. This can take several moments. If this value is true, a modal loading indicator will be displayed while comments are being loaded.

hoverClass

Type: String
Required: No
Default: tAnnotatableHover

The value of the HTML class attribute that is added to an annotatable element when the mouse is hovering over it. Subtly changing the look of the element gives the user feedback that it is clickable.

readOnly

Type: boolean
Required: No
Default: false

If this is set to true, comments from the server will be loaded, but editing, deleting, and creating comments will be prevented.

hintText

Type: String
Required: No
Default: 'Leave a comment'

The default text that appears in the comment entry box before the user starts typing.

slideDuration

Type: Integer
Required: No
Default: 100

Several interaction with the Comment Manager, such as loading comments, saving a new comment, and deleting comments, result in a "sliding" animation. This value sets the duration, in milliseconds, of the animation. A value of 0 will disable animations entirely.

render

Type: function(Object m, jQuery $e)
Required: No
Default:

function(m, $e) {
    if (m.safeHtml) {
        $e.html(m.safeHtml);
    } else {
        $e.text(m.message);
}

The function that controlls the rendering of comments. It takes two parameters; m is the message object itself, and $e is the element that will contain the body of the comment.

currentUserOnly

Type: boolean
Required: No
Default: false

Set this value to true if you want users to only be able to see comments they left, and not those by other users.

maxReplyDepth

Type: Integer
Required: No
Default: 1

This option sets how deeply replies can be nested relative to "top-level" comments. Setting to zero dissalows replying to comments.

Setting a high maxReplyDepth adds more flexibility to comment sections, but can have the undesireable affect of leading users to reply to a comment when it would have been more appropriate to leave that comment at a different level. Additionally, as each "level" of comments is indented, deep nesting can cause UI problems.

Reducing the maxReplyDepth of a comment thread, after replies have already been left beyond that level, will effectively hide those comments until the maxReplyDepth is increased again. It is not recommended to change this value after there has been activity in a comment thread.

addCommentLinkText

Type: String
Required: No
Default: 'Continue the conversation'

The addCommentLinkText is the text on the widget that allows users to add a comment to the end of a comment thread.

Titania Delivery Developer's Guide

Comment Management with the Titania Annotator Plugin

Related information: