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 the Forum app. The module is available in 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 at Configuration > /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 Forum app 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 at Configuration > /modules/commenting/templates/components/latestComments:

• parameters:
  
  • forumName: Comments are stored in the pagecomments forum created by the module. See Forum app 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.

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 configuration below adds the comments component to content area and the latestComments component to extras1 area of the stkSection template configured at STK > Template Definitions /pages/stkSection.

In the examples below dummy comments were added on 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 STK > Site Definitions /default/templates/prototype/areas/main/areas/comments/availableComponents.

The configuration above makes the comments component available on all templates, but it is in fact only available on the stkArticle template (and by extension on 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 at STK > Site Definitions /default/templates/prototype/areas/main/templateScript and STK > 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 STK > 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

To use IntenseDebate commenting 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 connector is configured in the stkComments component definition in STK > Template Definitions components/features/stkComments.

• parameters/intenseDebateId: Insert your intenseDebateId.
• dialog: stkComments dialog configured at STK > 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 STK > 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. info.magnolia.module.templatingkit.templates.CommentsArea

Here's the IntenseDebate commenting component on a page.

Forum app

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

Here are 's the comments we added in the previous examples on three /demo-project pages:

• 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, approve and reject messages.
• App permissions are configured in the Forum module. Default user eric (Example Editor (Demo Project)) has full permissions to the app, whereas peter (Example Editor (Demo Project)) cannot execute certain actions. See App permissions for more.

The Moderation subapp allows moderators to manage comments.

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

Security

Default roles

On installation the Commenting 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 forum workspace beyond the path /pagecomments. This means the user can create and read thread- and comment-nodes.

Disabling anonymous commenting

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

To grant a user permission to view, but not post, comments create a new role in Security > Roles and assign it to the anonymous user in Security > Systems Users.

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 users, if the role is added at Configuration > /modules/public-user-registration/config/configurations/default/defaultRoles.

Forum app permissions

Commenting administration and moderation permissions are granted in the Forum module. See Security for more information.

Multisite and multilanguage commenting

The Commenting module supports multisite (EE) and multilanguage commenting. These options are enabled by default at Configuration > /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 Configuration > /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.

Here are the forums with sample comments with both properties enabled.

To allow editors, moderators or anonymous users to post comments and access the forums create new roles in Security > Roles with the following names and permissions for each expected forum and assign them to the relevant user. * When you save the role the ACL to the Userroles workspace is created automatically.

Access control lists

Here are two sample comments posted anonymously on the public instance with the forumPerLocale and multiSite properties set to true and relevant roles assigned to the anonymous system user.

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 Configuration > /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 at Configuration > /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. You can set these in the Mail tools app accessible at Tools > Mail tools. See Mail for more information about using the app.  

Comments notification template

The pageCommentsNotification template is configured at Configuration > /modules/mail/config/templatesConfiguration/pageCommentsNotification. See Templates configuration for more information. The Observation module uses this mail template to send email notifications.

You can test this template in Verify Settings in the Mail tools app.

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 Configuration > /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.