Commenting

The Commenting module adds a commenting feature on any Magnolia page. The module is built on the Forum module and comments are managed in AdminCentral in Forums. The module is integrated with the STK.

The benefits of built-in commenting, as opposed to an external service include:

• You own the content, not an external service provider.
• 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 any other part of the site.
• In-place moderation of comments in the Forum app.

The STK also supports IntenseDebate, a third party commenting service.

Configuration

The module is configured in /modules/commenting.

Components

The module includes two components:

• Comments: Provides the commenting feature. By default the component is available on all STK content temples, i.e. stkArticle and its extensions, but you can make it available on any template. See Adding components to templates for more.
• Latest Comments: Is a teaser component that aggregates the most recent comments from a selected page. The component is not available by default, but you can add it to any template.

Here's the Comments component on the /demo-project/about/history page and Latest Comments component in extras area on a related page.

Comments component

The comments component provides the commenting functionality. When you add it to a page commenting is automatically enabled.

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

• parameters:
  
  • avatarImage: Default avatar image stored in the resources folder of the module jar (GIT).
  • forumName: Comments are stored in the pagecomments forum created by the module. See Forums for more.
• dialog: comments dialog has a single field, Alternative Text. The content renders if the user does not have permission to view or post comments. By default anonymous commenting is allowed. See Security for more.
• modelClass:  PageComments :
  
  • Creates a forum-node when a page with a comments-section is requested for the first time and if the forum-node doesn't already exist.
  • Creates a thread-node for the page if none exists, using the title or page name for the thread name.
  • Adds a comment (message) to the forum thread of the page.
  • Is early-execution aware and adds a query parameter to avoid serving cached content because flushing may take a while.
• templateScript: comments.ftl (GIT):
  
  • Renders the comment count in the component header.
  • Renders the comments (messages) as a ContentMapList, including the gravatar, title, message, username, date and inline reply link for each.
  • Includes the comment-form.inc.ftl (GIT) script that renders the form.

Latest Comments component

The Latest Comments component is a teaser that can be used in extras area to display comments made on a related page.

The latestComments component definition is in /modules/commenting/templates/components/latestComments.

• parameters:
  
  • forumName: Comments are stored in the pagecomments forum created by the module. See Forums for more.
• dialog: latestComments allows editor's to include a title, select the page that comments are sourced from, set the maximum number of comments, and set the description (message) length.
• modelClass:  LatestComments retrieves a list of the latest page comments for a specified page. 
• templateScript: latestComments.ftl (GIT) renders the component title, list of comments from the specified page, and respects any limitations set in the dialog.

Here's the latestComments dialog.

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. Here's the comments component in comments area of the /demo-project/about/history page in the website JCR browser, accessible in Tools > JCR Browser (Website).

Adding components to templates

You can add the commenting components to any template. The comments component adds the commenting feature automatically. Ideally the comments component should reside in it's own area, but there is no technical reason that it cannot be add to content area, for example. See Rendering comments area for an alternative STK method.

The example configurations below add the comments component to content area and the latestComments component to extras1 area of the stkSection template configured in STK > Template Definitions /pages/stkSection.

In the examples below dummy comments were added to the /demo-project/about/subsection-articles page and referenced on the /news-and-events page. Both pages are based on the stkSection template.

Standard Templating Kit

In the STK the comments component is made available in main/comments area in the template prototype. This is configured in Templating Kit > Site Definitions /default/templates/prototype/areas/main/areas/comments/availableComponents.

The configuration above makes the comments component available in all templates, but it is in fact only available in the stkArticle template (and by extension all content templates). This is because main area in the prototype is rendered by /templating-kit/pages/global/mainArea.ftl and in stkArticle by /templating-kit/pages/content/mainArea.ftl. You can find these configurations in Templating Kit > Site Definitions /default/templates/prototype/areas/main/templateScript and Templating Kit > Template Defintions /pages/stkArticle/areas/main/templateScript. See main and comments area for more.

<div id="main" role="main">
    [@cms.area name="breadcrumb" content=content/]
    [@cms.area name="intro" content=content/]
    [@cms.area name="content"/]
</div><!-- end main -->

 <div id="main" role="main">
    [@cms.area name="contentNavigation" content=content/]
    [@cms.area name="breadcrumb" content=content/]
    <div class="text" role="article">
        [@cms.area name="intro" content=content/]
        [@cms.area name="content"/]
    </div><!-- end text -->
    [@cms.area name="comments"/]
</div><!-- end main -->

Rendering comments area

You can use the cms:area directive to render the comments area on any template. Add [@cms.area name="comments"/] to the relevant main area template.

To demonstrate, we added the directive to /templating-kit/pages/global/mainArea.ftl that renders main area in the prototype. You can test this in Templating Kit > Templates:

1. Edit /templating-kit/pages/global/mainArea.ftl.
2. Add [@cms.area name="comments"/] to the template.
3. Select Enable template to ensure that it is served from the repository (templates workspace).
4. Save.

Here's the comments area on the stkImageGallery template.

IntenseDebate commenting

The STK is integrated with IntenseDebate commenting. To use this option you need to sign up for an account and get an intenseDebateId:

1. During the IntenseDebate sign up process, select the “I want to install IntenseDebate on my blog or website” option.
2. Select the “Generic Install” option.
3. Copy the code from the JavaScript Install box. The first line of code contains your ID, which will be similar to this:

var idcomments_acct = 'bb0230d1df6448c6043af8d3d1d4daac';

STK Comments component

The IntenseDebate integration is configured in the stkComments component definition in Templating Kit > Template Definitions components/features/stkComments.

• parameters/intenseDebateId: Insert your intenseDebateId.
• dialog: stkComments dialog configured at Templating Kit > Dialog Definitions/components/features/stkComments has a single hidden field. The editor sees a blank dialog that renders the stkComments component when saved.
• templateScript: comments.ftl (see below) adapts the script provided by IntenseDebate to render the component in Magnolia.

Enabling IntenseDebate commenting

To enable site-wide IntenseDebate commenting you need to substitute the STK Comments for the Magnolia Comments component in the prototype template at Templating Kit > Site Definitions /default/templates/prototype/areas/main/areas/comments:

• availableComponents/stkComments: Change the value of the id property to standard-templating-kit:components/features/stkComments.
• class: CommentsArea supports the intenseDebateId configuration property that is made available to the third party software.

Here's the IntenseDebate commenting component on a page.

Forums

Magnolia comments are administered and moderated in AdminCentral in Forums. Comments should be moderated on the public instance because this is where the content is generated. See Forum module for more information.

Here are the comments we added in the previous examples on the History and Articles pages in /demo-project:

• Comments are stored in the pagecomments forum that is created when the module is installed. The /modules/commenting/templates/components/comments/parameters/forumName node of the comments component points to this forum.
• 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.
• Each comment displays as a message.
• Administrators can lock threads, and edit, delete, validate and invalidate messages.

Messages can be edited in the Message dialog.

Security permissions

For more information about Magnolia security see Security.

Default roles

On installation, the Forum module creates the forum-base role and the Commenting module creates the forum-pagecomments-user, forum-pagecomments-moderator and forum-pagecomments-admin roles. These roles grant the following permissions in the Forum workspace.

These roles are not assigned to any user or group by default. superuser is assigned the forum-All-admin role that provides full permissions.

Anonymous commenting

The anonymous user (public user) does not have permission to comment or view comments. You can verify this by logging out of the public instance. The page comments disappear from the page.

To make page comments visible to anonymous users, on the public instance in Security > Systems Users:

1. Select anonymous.
2. Click Edit user.
3. In the Roles field assign the forum-base role.
4. Save.

Page comments will now be visible, but anonymous users will still be unable to post comments.

To allow public users to view and post comments, follow the procedure above, but assign the forum-pagecomments-user role to the anonymous user.

Public User Registration

You can use the Public User Registration module to require users to register before commenting. The module will automatically assign the forum-pagecomments-user role to new registered users, if the role is added in /modules/public-user-registration/config/configurations/default/defaultRoles.

Multisite and multilanguage commenting

The Commenting module supports multisite (EE) and multilanguage commenting. These options are enabled by default at /modules/commenting/config:

• forumPerLocale: Creates forums for each language defined in the locales node of the site defintion (EE) or server configuration (CE).
• multisite: Creates forums for each site defined in STK > Site definition (EE).

The comments component uses the pagecomments forum by default. This is set in the forumName property in /modules/commenting/templates/components/comments/parameters/forumName. To enable multisite and mulitlanguage commenting, delete the value "pagecomments" and leave it blank. The system will then create new forums automatically in the following formats:

• forumPerLocale enabled: pagecomments_<language identifier>. The forum for the defaultLocale, for example pagecomments_en, is created when you add the comments component to any page. The forums for additional locales, for example, pagecomments_de, are created when the first comment in the language is posted. 
• multiSite enabled: pagecomments-<site name>. A forum is created for each site, for example pagecomments-demo-project and pagecomments-demo-features, when the comments component is added to any page of the site.
• forumPerLocale and multiSite enabled: pagecomments-<site name>_<language identifier>. The forum for the defaultLocale, for example pagecomments-demo-project_en , is created when the comments component is added to any page of the site, and the forums for additional locales, for example pagecomments-demo-project_de, are created when the first comment in the language is posted.

Caching

Pages with comments are flushed from the server cache when new comments are posted. The Commenting module registers the  ReferencedPageFlushPolicy class that takes care of this. The configuration is at /modules/cache/config/configurations/default/flushPolicy/policies/FlushByComments. See Cache module for more information.

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. The example configuration below disables the cache for the /demo-project/about/history page.

Mail notifications

SMTP settings

For mail notifications to be sent valid SMTP settings need to be configured in the Mail module. Go to Configuration > Mail (SMTP) to check your settings.

Comments notification template

The pageCommentsNotification template is configured in /modules/mail/config/templatesConfiguration/pageCommentsNotification. See Tempate based messages for more information. The Observation module uses this mail template to send email notifications.

You can test this template in Tools > Mail > Template message configuration.

Observing comments

The sendMailOnPageComments event listener observes the forum workspace and sends a preconfigured email when a new comment is posted. This is one of the listener configurations that is overridden when you install the Observation module. See Observation module for more information about configuring listeners.

To use the listener:

1. Import the sendMailOnPageComments event listener into the /modules/observation/config/listenerConfigurations node.
2. Change the active property to true.
3. Enter valid email addresses for the from and mailTo properties.

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.
• Performance and high availability for a more detailed discussion on tried and tested configurations.
• 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.