Magnolia Commenting module is a Community Edition module that enables the commenting feature on any page managed by Magnolia CMS. The Commenting module is built on the Forum module and comments are managed in Forums. The commenting module also supports IntenseDebate, a third party commenting service.

The benefits of Magnolia Commenting are:

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

• Download
• Installing
• Uninstalling
• Video
• Enabling commenting
• Magnolia commenting
• Configuration
• comments paragraph
• latestComments paragraph
• Moderating
• Security permissions
• Default roles
• superuser
• anonymous
• Moderators and administrators
• Mail notifications
• Mail module
• Observation module
• Disabling cache
• Systems architecture
• IntenseDebate commenting
• Sign up with IntenseDebate
• Insert ID in the STK
• stkComments paragraph
• Adding commenting to templates
• Amend mainArea.ftl
• Make paragraph available
• Enable commenting

Download

Download the Commenting module from Magnolia Store.

Installing

Commenting is a Enterprise Edition module (4.0 and higher) included in the Standard Templating Kit bundle and typically already installed. Go to Magnolia Store > Installed modules in AdminCentral to check. To install the module individually, see the general module installation instructions.

Uninstalling

See the general module uninstalling instructions and advice.

Video

Watch a video about commenting.

Enabling commenting

By default, commenting can be enabled on all pages based on the content templates, i.e. stkArticle. stkLargeArticle, stkNews, stkEvent and stkGlossaryTerm. This functions in the same way in both editions, but the paragraph that is rendered differs. To demonstrate, we use the /demo-project/about/subsection-articles/article page.

To enable commenting:

1. Open any page based on a content template.
2. At the bottom of the page click Enable commenting and save the dialog.
   
   

In CE, the stkComments paragraph that integrates with IntenseDebate appears.

To disable commenting click Disable Commenting. When disabled, comments are hidden, but not deleted, and will be restored when commenting is again enabled.

Magnolia commenting

In the default installation, sample comments are included on the demo-project/about/history page. Enable commenting on this page to view them.

The Commenting module is built on the Forum module and comments are managed in Forums.

Configuration

The Commenting module includes two paragraphs and associated dialogs: comments and latestComments. The paragraph and dialog definitions are configured at Configuration > /modules/commenting/paragraphs and /dialogs.

comments paragraph

The comments paragraph definition is configured at Configuration > /modules/commenting/paragraph/comments. The definition uses the PageComments model class that determines the logic of the paragraph.

In the /comments/parameters node:

• The forumName property references that pagecomments forum that is created on installation. See Moderating below.
• The avatarImage property links to the avatar image rendered by the paragraph next to each username.

The comments dialog definition is configured at Configuration > /modules/commenting/dialogs/comments.

This dialog has a single fckEdit field, alternativeText. The text inserted in this field is displayed to users who do not have permission to post comments. See Security permissions below.

In the STK, the comments paragraph is available in the template prototype, accessible at Templating Kit > Site Definitions > /default/templates/prototype/mainArea/comments. This paragraph is available on all templates on which commenting is enabled, i.e. stkArticle. stkLargeArticle, stkNews, stkEvent and stkGlossaryTerm.

The /comments/intenseDebateId node should be left blank when using Magnolia commenting. It provides the option to use IntenseDebate commenting as an alternative.

Commenting can be enabled on all templates and this is demonstrated later in Adding commenting to templates.

latestComments paragraph

The latestComments paragraph aggregates the most recent comments from a selected page and renders them in the paragraph.

The latestComments paragraph definition is configured at Configuration > /modules/commenting/paragraphs/latestComments. To use this paragraph, amend the default configuration as follows:

1. Change the type property from freemarker to stk.
2. Add a divClass data node to the /parameters content node and leave the value blank.
3. Add a headingLevel data node to the /parameters content node and set the value to h2.

The latestComments dialog definition is configured at Configuration > /modules/commenting/dialogs/latestComments. This dialog has four fields: title, parentPath, limit and maxLength that allow you to control the content rendered by the latestComments paragraph.

By default, the latestComments paragraph is not available on any of the STK templates, but can be added to mainArea or extrasArea of any template.

To make the latestComments paragraph available on any template, in Templating Kit > Template Definitions:

1. Select the relevant template.
2. Add a content node to the /mainArea/paragraphs or /extrasArea/paragraphs node and name it latestComments. If the template does not have a extrasArea node because it uses the prototype configuration, you will also need to add an extrasArea/paragraphs node to the template definition.
3. Add a data node to the /latestComments node, name it name and set the value to latestComments.

To add the paragraph to a page, click New and select the latestComments paragraphin the Create new paragraph dialog. In the latestComments dialog:

• Title includes the paragraph title.
• Search Path allows you to select the page from which the comments are rendered. If no path is selected the entire site is used.
• Limit determines the number of messages displayed.
• Max description length limits the number of characters for each message.

The screenshot below shows the latestComments paragraph in extrasArea of the /demo-project/about/subsection-articles/article page.

Moderating

Comments are managed in Forums and on installation the Commenting module creates the pagecomments forum.

As comments are user generated content, they should be moderated on the public instance.

To demonstrate moderation, we enabled commenting on the demo-project/news-and-events/news-overview/news01 page, activated the page and entered a number of comments on the public instance.

When the first comment is posted, in Forums a new thread is created for the page and each comment displays as an individual message.

Among other functions, commenting on the page can be locked or unlocked i.e. allowed or terminated.

Messages can be validated or invalidated i.e. displayed or not displayed, and edited and deleted.

Security permissions

For more information about Magnolia security, please refer to 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 users or groups by default.

superuser

By default, superuser has Read only permissions in the Forum workspace, but for testing purposes you may want to increase these permissions.

To grant superuser moderator permissions, in Security > Systems Users:

1. Select superuser.
2. Click Edit user.
3. In the Roles field, assign the forum-pagecomments-moderator role.
4. Save.

anonymous

By default, Forum module security does not permit anonymous public users to view forum paragraphs. The anonymous systems user does not have permissions to read the forum workspace. 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, 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 an anonymous user will be unable to post comments. The text inserted in the alternativeText field of the comments dialog displays in place of the form.

The forum-pagecomments-user role provides write permissions to the pagecomments forum. You can grant this permission to individual public users by hand in Security > Public Users or automate the role assignment in the Public User Registration module.

To automate, configure the forum-pagecomments-user roles as a sub node in Configuration > /modules/public-user-registration/config/defaultRoles. The Public User Registration module will assign the role to new public users when they register.

Moderators and administrators

The forum-pagecomments-moderator and forum-pagecomments-admin roles allow access to the moderation UI in Forums for the /pagecomments forum. This allows the user to moderate and delete posts. The only difference between these roles is that the latter can additionally activate, but this is typically not needed as moderation takes place on the public instance.

To grant a user permission to moderate page comments, in Security > Users:

1. Create a new user.
2. Assign the user to the /demo-project-editors group.
3. Assign the forum-pagecomments-moderator role to the user.

Mail notifications

It is possible to enable mail notifications for new comments posted on the site. To use this feature the Mail and Observation modules need to be installed.

Mail module

For mail notifications to be sent valid SMTP settings should be configured at Configuration > /modules/mail/config/smtp. For more information, please refer to Configuring SMTP.

The Observation module uses the pageCommentsNotification template to send email notifications. See Observation module below. This template is configured in Configuration > /modules/mail/config/templatesConfiguration/pageCommentsNotification. For more information about configuring mail templates, please refer to Registering a template.

Observation module

In the default installation, the sendMailOnPageComments event listener is configured to send a mail notification when comments are posted. This configuration is at Configuration > /modules/observation/config/listenerConfigurations/sendMailOnPageComments.

To enable email notifications make the following amendments to this configuration:

1. In the /sendMailOnPageComments/listener node change the value of the active property to true.
2. In the /sendMailOnPageComments/listener/params node insert valid email addresses for the from and mailto properties.

For more information about listeners, please refer to Defining an event listener.

Disabling cache

The ReferencedPageFlushPolicy Java class takes care of flushing pages from the server cache when new comments are posted. This class is registered in the Cache module at Configuration > /modules/cache/config/configurations/default/flushPolicy/policies/FlushByComments.

It is also advisable to disable the cache for individual pages that use comments. To do this, at Configuration > /modules/cache/config/configurations/default/cachePolicy/voters/urls/excludes:

1. Copy the dotMagnolia node and rename it appropriately.
2. Enter the page URL in the Value column of the pattern property.

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:

1. Clustering for an overview of typical systems architecture.
2. Performance and high availability for a more detailed discussion on tried and tested configurations.
3. 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.

IntenseDebate commenting

In CE, comments are managed and moderated in your IntenseDebate account, which offers a host of features. The STK is fully integrated with IntenseDebate and all that is necessary is to enter your IntenseDebate ID in the STK.

Sign up with IntenseDebate

Go to IntenseDebate and create a free account:

1. On the sign up form, select the “I want to install IntenseDebate on my blog or website” option.
2. Once you have verified your email address, on the Install IntenseDebate screen, select the “Generic Install” option.
3. In the JavaScript Install panel, copy the code from the first box. The first line of code contains your IntenseDebate ID, which will be similar to this:

var idcomments_acct = 'bb0230d1df6448c6043af8d3d1d4daac';

Insert ID in the STK

Once you insert your IntenseDebate ID in the STK, all templates will inherit it.

To insert your ID, go to Templating Kit > Site Configuration and insert your ID in /templates/prototype/mainArea/comments/intenseDebateId node.

If you want to use multiple IntenseDebate accounts, you can override the default ID on an individual template level. This could be useful, for example, to keep commenting moderation on news and article pages separate.

To override the default ID in Templating Kit > Template Definitions:

1. Select the relevant template.
2. Add a sub node to the /mainArea node and name it comments.
3. Add a data node to the /comments sub node, name it intenseDebateId and insert the new account number in the Value column.

stkComments paragraph

The stkComments paragraph is available in the prototype template, accessible at Templating Kit > Site Configuration > /templates/prototype/mainArea/comments. This paragraph is available on all templates on which commenting is enabled, i.e. stkArticle. stkLargeArticle, stkNews, stkEvent and stkGlossaryTerm.

Commenting can be enabled on all templates and this is demonstrated later in Adding commenting to templates.

The stkComments paragraph definition is configured at Templating Kit > Paragraph Definitions > /features/stkComments.

The stkComments dialog definition is configured at Templating Kit > Dialog Definitions > /paragraphs/features/stkComments. This dialog contains a single hidden field. When you enable commenting on a page, a blank dialog opens and the stkComments paragraph is rendered when you save the dialog.

Adding commenting to templates

In this section, we demonstrate how to add commenting to a template where it is not available by default. We use the stkImageGallery template as an example, but these steps can be adapted for any template. In the examples, if you are using CE, you need to substitute the stkComments paragraph for the comments paragraph (EE) used in the examples.

Amend mainArea.ftl

All STK templates rely of the MainArea Java class which gets and sets the MainAreaIntro and CommentsArea.

The STK templates are mostly distinguishable by the content options available in /mainArea. With the exception of the content templates, most templates rely on a specific mainArea.ftl template. For example in the template definition, stkSection/mainArea/template references /templating-kit/templates/section/mainArea.ftl, whereas stkFAQ references /templating-kit/templates/singleton/mainArea.ftl.

To enable commenting on a template, the first step is to amend the relevant mainArea.ftl script. To demonstrate, we amend /templating-kit/templates/singleton/mainArea.ftl that is used by all special templates.

In Templating Kit > Templates:

1. Select mainArea.ftl in /templating-kit/templates/singleton and click Edit template.
   
   
2. In the Edit dialog, add the code detailed below at the end of the template script.
3. Select the Enable template option to ensure that the template is served from the repository.
4. Save.

[#if content[def.mainArea.comments.paragraph]?has_content]
    [@cms.includeTemplate contentNodeName="${def.mainArea.comments.paragraph}" /]
[#else]
    [#if mgnl.editMode]
        <div style="padding-top: 20px;">
            [@cms.newBar contentNodeName="${def.mainArea.comments.paragraph}" paragraph="${def.mainArea.comments.paragraph}" newLabel="${i18n['comments.newLabel']}" /]
        </div>
    [/#if]
[/#if]

This method works equally for the stkSection template and the relevant script is available in /templating-kit/templates/section/mainArea.ftl.

Make paragraph available

The next step is to make a commenting paragraph available to the template.

In Templating Kit > Template Definitions:

1. In /stkImageGallery, add a sub content node to the /mainArea node and and name it comments.
2. Add a data node to the /comments node, name it paragraph and insert comments (EE) or stkComments (CE) in the Value column.

Enable commenting

In Website, open the /demo-project/multimedia/image-gallery page, click Enable commenting at the bottom of the page and save the dialog. The commenting paragraph made available to the template appears.