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

The Commenting module is built on the Forum module and comments are managed in the Forum app. The Forum module functionality is no longer provided in Magnolia 5.5, however it continues to exist to serve Commenting purposes.

This page will be updated soon.

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:

The components are not styled by default. You need to add your own CSS styles.

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:

Node nameValue

 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

freemarker

 templateScript

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

 title

paragraph.comments.title 

Properties:

comments 

parameters

 

avatarImage

Default avatar image stored in the resources folder of the module jar (GIT).

forumName

The module creates the pagecomments forum for comments storage. See Forum app.

dialog

A simple dialog with one field, Alternative Text. The text displays to users who do not have permission to view or post comments. By default anonymous commenting is allowed. See Security.

modelClass

PageComments contains the commenting business logic. The model:

  • Creates a forum-node, if none exists, when a page with comments is requested for the first time.
  • Creates a thread-node for the page if none exists, using the title or page name as 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.

See Administering and moderating comments for more.

renderType

Change this property to freemarker if necessary.

templateScript

comments.ftl (GIT):

  • Renders the comment count.
  • Renders the comments (messages).
  • Includes the comment-form.inc.ftl (GIT) script that renders the commenting form.

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:

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

freemarker

 templateScript

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

 title

paragraph.latestComments.title 

Properties

latestComments 

parameters

Comments are stored in the pagecomments forum created by the module. See Administering and moderating comments.

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.

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.

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

Node nameValue

 news

 

 comments

 

 0

 

 alternativeText

<p>Please <a href="${link:{uuid:{f46be550-7c16-4ec6-82a5...">login</a> to comment.</p>

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.

/my-module/templates/pages/myTemplate.yaml
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 
Node nameValue

 myTemplate

 

 areas

 

 main

 

 availableComponents

 

 textImage

 

 linkList

 

 latestComments

 

 id

commenting:components/latestComments

 comments

 

 availableComponents

 

 comments

 

 id

commenting:components/comments

 type

single

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

Comments should be managed and moderated on the public instance because this is where the content is generated.

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.
ActionsAdministrators can lock threads, and edit, delete, approve and reject messages.
PermissionsApp 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.
ActionsModerators 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  Forum module.

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. 

RolePermissionScopePath

forum-pagecomments-user

Read/Write

Selected and sub nodes

/pagecomments

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.

RolePermissionScopePath

forum-pagecomments-view

Read only

Selected and sub nodes

/pagecomments

Public User Registration

It is possible to require users to register before commenting using the Public User Registration module that is not yet available for (warning) Magnolia 5.4+

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:

Node nameValue

 commenting

 

 config

 

 forumPerLocale

true

 multiSite

true

 nestedCommentsByDefault

false

Properties

configConfiguration node of the module.

forumPerLocale

optional, default is true

Creates forums for each language defined in the locales node of the site defintion.

multisite

optional, default is true

Creates forums for each site defined in the site definition (EE Pro).

nestedCommentsByDefault

optional, default is false

Enables message nesting by default.

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:

forumPerLocale (only)Creates language-specific forums in the pagecomments_<language identifier> format. 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 (only)Creates site-specific forums in the pagecomments-<site name> format. A forum is created for each site, for example pagecomments-travel and pagecomments-sportstation, when the comments component is added to any page of the site.
forumPerLocale and multiSite (both)Creates site and language-specific forums in the pagecomments-<site name>_<language identifier> format. The forum for the defaultLocale, for example pagecomments-travel_en , is created when the comments component is added to any page of the site, and the forums for additional locales, for example pagecomments-travel_de, are created when the first comment in the language is posted.

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.

Role nameWorkspacePermissionScopePath
forum-<forum-name>-userForumRead/WriteSelected and sub nodes/<forum-name>

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 ReferencedPageFlushPolicy class that takes care of this.

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

Node nameValue

 cache

 

 config

 

 contentCaching

 

 defaultPageCache

 

 flushPolicy

 

 policies

 

 flushAll

 

 FlushByComments

 

 workspaces

 

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

Node nameValue

 config

 

 contentCaching

 

 defaultPageCache

 

 cachePolicy

 

 shouldBypassVoters

 

 urls

 

 includes

 

 excludes

 

 dotMagnolia

 

 comments-about

 

 class

info.magnolia.voting.voters.URIStartsWithVoter

 pattern

/travel/about

 restCache

 

 not

true

 level

1

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. The Observation module is not yet available for (warning) Magnolia 5.4+.

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: