Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

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.

Node nameValue

 modules

 

 commenting

 

 config

 

 dialogs

 

 templates

 

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:

Node nameValue

 commenting

 

 templates

 

 components

 

 comments

 

 parameters

 

 avatarImage

/docroot/commenting/avatar.jpg

 forumName

pagecomments 

 description

paragraph.comments.description 

 dialog

commenting:comments 

 i18nBasename

info.magnolia.module.commenting.messages 

 modelClass

info.magnolia.module.commenting.frontend.action.PageComments 

 renderType

stk

 templateScript

/info/magnolia/module/commenting/frontend/comments.ftl 

 title

paragraph.comments.title 
  • 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.
  • dialogcomments 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:

Node nameValue

 commenting

 

 templates

 

 components

 

 latestComments

 

 parameters

 

 forumName

pagecomments

 description

paragraph.latestComments.description 

 dialog

commenting:latestComments 

 i18nBasename

info.magnolia.module.commenting.messages 

 modelClass

info.magnolia.module.commenting.frontend.action.LatestComments 

 renderType

stk

 templateScript

/info/magnolia/module/commenting/frontend/latestComments.ftl 

 title

paragraph.latestComments.title 
  • 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.

Node nameValue

 history

 

 comments

 

 0

 

 alternativeText

<p>Please <a href="${link:{uuid:{7b17a30a-e8bb-4...

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.

Node nameValue

 pages

 

 stkSection

 

 areas

 

 main

 

 areas

 

 intro

 

 opener

 

 content

 

 availableComponents

 

 stkTeaser

 

 ...

 

 comments

 

 id

commenting:components/comments

 templateScript

/templating-kit/pages/section/contentArea.ftl

 title

templates.stkSection.areas.main.content.title

 class

info.magnolia.module.templatingkit.templates.SectionMainArea 

 templateScript

 /templating-kit/pages/section/mainArea.ftl

 extras

 

 areas

 

 extras1

 

 availableComponents

 

 latestComments

 

 id

commenting:components/latestComments

 sectionHeader

 

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.

Node nameValue

 default

 

 templates

 

 prototype

 

 areas

 

 main

 

 areas

 

 intro

 

 comments

 

 availableComponents

 

 stkComments

 

 id

commenting:components/comments

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.

Prototype

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

Article

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

This is a better alternative than Adding components to templates if you use the STK.

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.
Node nameValue

 components

 

 features

 

 stkComments

 

 parameters

 

 intenseDebateId

b3828276089a657d0394e1ff40b5f505

 description

paragraphs.content.stkComments.description

 dialog

standard-templating-kit:components/features/stkComments

 i18nBasename

info.magnolia.module.templatingkit.messages

 renderType

stk

 templateScript

/templating-kit/components/features/comments.ftl

 title

paragraphs.content.stkComments.title

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
Node nameValue

 default

 

 templates

 

 prototype

 

 areas

 

 main

 

 areas

 

 intro

 

 comments

 

 availableComponents

 

 stkComments

 

 id

standard-templating-kit:components/features/stkComments

 class

info.magnolia.module.templatingkit.templates.CommentsArea

 description

areas.templates.main.comments.description

 title

areas.templates.main.comments.title 

 type

single 

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.

The Forum module has a number of configuration properties that control, for example, whether messages are rendered immediately or only after validation. See Configuration for more information.

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.

RolePermissionScopePath

forum-pagecomments-user

Read/Write

Selected and sub nodes

/pagecomments

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.

RolePermissionScopePath

forum-pagecomments-view

Read only

Selected and sub nodes

/pagecomments

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.

Node nameValue

 modules

 

 public-user-registration

 

 config

 

 configurations

 

 default

 

 defaultRoles

 

 anonymous

anonymous

 pur

public-user-registration-base

 comments

forum-pagecomments-user

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).
Node nameValue

 modules

 

 commenting

 

 config

 

 forumPerLocale

true

 multiSite

true

 nestedCommentsByDefault

false

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

Role nameWorkspacePermissionScopePath
forum-<expected-forum-name>-userForumRead/WriteSelected and sub nodes/<expected-forum-name>
 UserrolesRead onlySelected/<role name>*

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.

Node nameValue

 modules

 

 cache

 

 config

 

 configurations

 

 default

 

 cachePolicy

 

 browserCachePolicy

 

 executors

 

 flushPolicy

 

 policies

 

 flushAll

 

 FlushByComments

 

 repositories

 

 o

forum

 class

info.magnolia.module.commenting.cache.ReferencedPageFlushPolicy

 class

info.magnolia.module.cache.DelegateFlushPolicy

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.

Node nameValue

 config

 

 configurations

 

 default

 

 cachePolicy

 

 voters

 

 urls

 

 includes

 

 excludes

 

 dotMagnolia

 

 comments-history

 

 class

info.magnolia.voting.voters.URIStartsWithVoter

 pattern

/demo-project/about/history

 not

true

 level

1

 deny

 

Mail notifications

This section requires the Observation module that is not installed by default, even though other modules bootstrap configurations to the Configuration > /modules/observation/config/listenerConfigurations node. If you do not see a /observation/version node the module is not installed. Before installing the module export the versionTemplatesOnChange, versionResourcesOnChange, sendMailOnPageComments and generateCategories listener configurations for later use. These are useful and will be overridden on installation of the module.

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

PageCommentsNotification.ftl script throws an exception when retrieving page link. See MGNLCMNT-103.

Node nameValue

 modules

 

 mail

 

 config

 

 templatesConfiguration

 

 pageCommentsNotification

 

 contentType

html 

 subject

This is a test email for freemarker template 

 templateFile

/info/magnolia/module/commenting/PageCommentsNotification.ftl 

 type

freemarker 

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. 
Node nameValue

 modules

 

 observation

 

 config

 

 listenerConfigurations

 

 sendMailOnPageComments

 

 listener

 

 command

 

 class

info.magnolia.module.mail.commands.MailCommand

 params

 

 model

 

 class

info.magnolia.module.commenting.PageCommentNotifModel

 from

robot@your-company.com 

 mailTemplate

pageCommentsNotification 

 mailTo

group-pagecomments-managers@your-company.com 

 subject

New Page Comment 

 type

freemarker 

 class

info.magnolia.module.observation.commands.RestrictToNodeTypeEventListener 

 nodeType

mgnl:message 

 active

true

 delay

31

 description

A mail will be sent when a page comment is added 

 eventTypes

NODE_ADDED 

 includeSubNodes

true

 maxDelay

40

 path

/pagecomments/

 repository

 forum

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: