Using commenting

The Commenting module adds complete commenting functionality to any Magnolia page. 

Built-in commenting has many benefits:

• Comments are indexed as Magnolia-native content, meaning search results will point to the page where the comment was made.
• Comments from any part of the site can be aggregated and shown in another part of the site.
• In-place moderation of comments in the Forum app.
• You own the content, not an external service provider.

Components

The module includes two components that you can add to your templates:

• Comments: Adds commenting functionality.
• Latest Comments: Aggregates the most recent comments from a selected page.

Comments component

The Comments component:

• Enables commenting functionality on any page by simply adding the component.
• Automatically displays public comments as users add them. Details include comment count, topic, message, username, date and reply link (for nested comments).
• Includes a commenting form.
• Integrates with the Forum app for easy comment administration.

The component definition is in /modules/commenting/templates/components/comments:

Properties:

Latest Comments component

Latest Comments component teases comments:

• The component is typically used on a different, but related page, to the page where the comment was made.
• Editors can select the source page for the comments which could be a single page or branch.
• Editors can limit the number of comments and the description (message) length.

Here's the associated component dialog.

The latestComments component definition in /modules/commenting/templates/components /latestComments:

Properties

Component storage

Page comments are stored in and rendered from the forum workspace. Only properties defined in the component dialogs are stored in the website workspace.

Example:  comments component in the  comments area of an example /news page in the JCR browser accessible in Tools > JCR.

Adding components to templates

You can add the commenting components to any template. To keep things organized the comments component should ideally reside in it's own area, but there is no technical reason barring you from adding it to an existing area.

Example: Template definition with comments component added to comments area and latestComments component to main area.

templateScript: /my-module/templates/pages/my-script.ftl
renderType: freemarker
visible: true
title: My template
areas:
  main:
    availableComponents:
      textImage:
        id: mtk:components/textImage
      linkList:
        id: mtk:components/linkList
      latestComments:
        id: commenting:components/latestComments
  comments:
    type: single
    availableComponents:
      comments:
        id: commenting:components/comments 

Use the cms:area directive to render the new comments area on any template.

Example: Adding comments area to a page script.

<div class="main">
    @cms.area name="main"/]
</div>

<div class="comments">
    [@cms.area name="comments"/]
</div>

Administering and moderating comments

Administrators administer and moderate comments in the Forum app.

Forum	Comments are stored in the pagecomments forum created when the module is installed. The /parameters/forumName node of the  comments component points to this forum
Thread	A thread is created for each page when the first comment is posted. The page title is used as the thread title, and failing that the page name.
Message	Each comment displays as a message.
Actions	Administrators can lock threads, and edit, delete, approve and reject messages.
Permissions	App permissions are configured in the Forum module. See App permissions

Moderators manage comments in the Moderation subapp.

Comment	Each comment displays in a row. The page is identified in the Thread column.
Actions	Moderators can edit, delete, approve and reject messages.

Commenting permissions

Permissions allow you to control who may comment of the public site and which staff members can access and moderate comments.

Anonymous commenting

Anonymous commenting is allowed by default.

The module creates the forum-pagecomments-user role and assigns it to the anonymous user on the author and public instances. 

This gives public users permission to read and write in the /pagecomments path of the forum workspace. This means the user can create and read thread- and comment-nodes.

To disable anonymous commenting, on the public instance remove the forum-pagecomments-user role from the anonymous user in the Security app. The comments will disappear from the page.

To grant the anonymous user permission to view, but not post, comments create a new role and assign it to the anonymous user.

Forum app permissions

Commenting administration and moderation permissions are granted in the Forum module.

Multisite and multilanguage commenting

The Commenting module supports multisite (EE Pro) and multilanguage commenting.

Configuration

The multisite and multilanguage options are enabled by default in /modules/commenting/config:

Properties

Enabling commenting for multiple sites and languages

To enable multisite and mulitlanguage commenting, delete the value "pagecomments" in the template definition of the Comments component in /modules/commenting/templates/components/comments/parameters/forumName. Leave the value blank.

The system will then create new forums automatically in the following formats provided the configuration properties are enabled:

In this example both configuration properties were enabled.

The module also creates user roles in the Security app for the new forums in the same sequence that the forums are created. The roles have the following format and permissions.

Use these roles to allow editors, moderators or anonymous users to post comments and access the forums. 

Caching

Pages with comments are flushed from the server cache when new comments are posted. The module registers the 

The flush policy configuration is in > /modules/cache/config/contentCaching/defaultPageCache/flushPolicy/policies/FlushByComments. See Cache modules for more.

You can also disable the cache for individual pages that use comments in > /modules/cache/config/configurations/default/cachePolicy/voters/urls/excludes. Duplicate the dotMagnolia node and set the pattern to the page URL.

Example: Disabling the cache for the /travel/about page.

Mail notifications

It is possible to configure Magnolia to send mail notifications when comments are posted. This functionality relies on the Mail and Observation modules. When a new node is created in the comments workspace this can be observed and the mail command executed. Have a look at this blog post for inspiration (see the section on "Email Notifications"). 

Systems architecture

From a system architecture point of view, dealing with high volumes of comments can be challenging. User-generated content POST requests differ from other content requests in that they cannot be served from cache and have the potential to cause bottlenecks during peak load times.

Magnolia can be configured to run in a clustered environment that provides high availability and load balancing. Content sharing between multiple instances is ensured by Jackrabbit’s clustering feature. For more information about running Magnolia in a Jackrabbit clustered environment, see:

• Clustering  for an overview of typical systems architecture.
• Empowering Magnolia for Enterprise Use Cases presentation at the 2010 Magnolia conference. Magnolia partner Aperto demonstrated a custom solution as an alternative to Jackrabbit clustering.