Commenting module

Edition

Incubator (services)

Issues

COMMENTING

Git

Git

Latest

1.1.4

Compatible with Magnolia 6.2, 6.1.4.

This module offers commenting features as well as the possibility of liking or disliking comments. You can moderate comments or mark as author´s favourite. The commenting module provides a REST API for commenting and a Content App to view comments of an item.

It uses an external database to store the commenting data.

This module is at the INCUBATOR level.

Installing with Maven

Maven is the easiest way to install the module. Add the following to your bundle.

Don’t forget about the JDBC drivers.
App config
<dependency>
  <groupId>info.magnolia.commenting</groupId>
  <artifactId>magnolia-commenting-app</artifactId>
  <version>1.1.4</version>
</dependency>
Rest config
<dependency>
  <groupId>info.magnolia.commenting</groupId>
  <artifactId>magnolia-commenting-rest</artifactId>
  <version>1.1.4</version>
</dependency>

Ensure the Tools module is part of your webapp.

Webapp
<dependency>
  <groupId>info.magnolia.tools</groupId>
  <artifactId>magnolia-tools</artifactId>
  <version>1.9.2</version>
</dependency>

JDBC drivers

You’ll also need to make sure you have your desired JDBC driver as part of your webapp.

MySQL
<dependency>
  <groupId>mysql</groupId>
  <artifactId>mysql-connector-java</artifactId>
  <version>${mysql.version}</version>
</dependency>
Postgres
<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>${postgresql.version}</version>
</dependency>

If you want to use an IDE like Eclipse or IntelliJ, you will need to configure the agent based on the ebean framework as described in the following: https://ebean.io/docs/getting-started/eclipse-ide.

Usage

This section guides you on setting up the module.

It contains the following sections:

Define the database connection

You can configure the database connection in the JCR or the File System (YAML) under: /src/main/resources/commenting-core/config.yaml.

For MySQL

/commenting-core/config.yaml
datasource:
    username: user
    password: password
    url: jdbc:mysql://127.0.0.1:3306/comments
    driver: com.mysql.cj.jdbc.Driver
    migration:
        path: dbmigration/mysql
        run: true

If you have an error like:

error
 "Error initialising DataSource: The server time zone value 'CEST' is unrecognized or represents more than one time zone. You must configure either the server or JDBC driver"

Add the following code to your url property in config.yaml: "?serverTimezone=Europe/Madrid" or your personal time zone, as described bellow:

/commenting-core/config.yaml
datasource:
    username: user
    password: password
    url: jdbc:mysql://127.0.0.1:3306/comments?serverTimezone=Europe/Madrid (1)
    driver: com.mysql.cj.jdbc.Driver
    migration:
        path: dbmigration/mysql
        run: true
1 Add your timezone replacing Europe/Madrid with Europe/Dublin for example.

For PostgreSQL

The snippet below doesn’t actually create the database, but rather points to it. Therefore, the defined database must already exist.

Ensure that the existing databse you’re using has the following rights:

  • CREATE

  • DROP

  • ALTER
/commenting-core/config.yaml
datasource:
    username: user
    password: password
    url: jdbc:postgresql://localhost:5432/comments
    driver: org.postgresql.Driver
    migration:
        path: dbmigration/pg
        run: true

Database schema

The table(s) required are created automatically by the init scripts in the magnolia-commenting-core module. For these scripts to be executed the first time the module is installed (or whenever the database is empty) the migration node in the datasource is used:

  • path: The path of the init script.

    • dbmigration/mysql for MySQL schema

    • dbmigration/pg for PostgreSQL schema

  • run: this property needs to be true when the database is empty.

    Default value: false

Anonymous comments

If you need anonymous comments in your site, add the following to your commenting-rest module:

commenting-rest/config.yaml
config:
  allowAnonymous: true

Cache

Be aware on Public instances, anonymous comments is cached on Magnolia by default.

To prevent caching, add an entry in cache’s excludes section for URIs starting with "/.rest/commenting".

Limit requests

To configure a limit on the request see Throttling Filter.

Content App Comments

Content App is hidden because it has no sense to view all comments without filter by an item. To view comments of a concrete item you need to select a node from a workspace and then click on "View Comments" action:

admincentral view comments

Once you have clicked on the action, you can view the "Comments" app per item selected:

admincentral view comments list

In this app you can:

  • View comments (and their details).

  • Delete comments.

  • Moderate comments.

  • Author choice: favourite comment from Editors.

You can configure the action on each ContentApp simply by adding "commenting" action like the following example:
Add Commenting Action
subApps:
  browser:
    actions:
      commenting:
        appName: commenting
        class: info.magnolia.commenting.action.BrowseCommentingActionDefinition
        icon: icon-message
        subAppId: browser
        availability:
          writePermissionRequired: false
          rules:
            IsNotDeletedRule:
              implementationClass: info.magnolia.ui.framework.availability.IsNotDeletedRule

    actionbar:
      sections:
        pageActions:
          groups:
            editActions:
              items:
                commenting: {}

Database action triggers

DB action triggers is a feature that allows triggering (calling) magnolia commands based on database action (CRUD). There are three types of actions that can be triggered:

To allow DB actions to trigger commands, we need to set magnolia property. Please set ebean.listeners.enabled to "true" in the corresponding magnolia.properties file.

ebean.listeners.enabled = true

Database trigger pass affected Entity objects to the command through the context. The User is able to get the Entity object (for example: info.magnolia.commenting.domain.Comment) from the context (object is passed to context by key "data").

Comment comment = (Comment) ctx.get("data");

Persist

To execute magnolia command on persist (add) DB action:

  • name command: prePersist or postPersist

    • prePersist is triggered before persist (add) action

    • postPersist is triggered after persist (add) action

  • put command definition in catalog that is named based on the database entity for which we want to trigger command

Example
'commenting-core':
  'commands':
    'comment':
      'postPersist':
        'class': 'info.magnolia.module.mail.commands.MailCommand' (1)
1 Sends an email message when a new comment is added to the database.

Update

To execute magnolia command on update DB action:

  • name command: preUpdate or postUpdate

    • preUpdate is triggered before update action

    • postUpdate is triggered after update action

  • put command definition in catalog that is named based on the database entity for which we want to trigger command

Example
'commenting-core':
  'commands':
    'comment':
      'postUpdate':
        'class': 'info.magnolia.module.mail.commands.MailCommand' (1)
1 Send an email message when a comment is updated in the database.

Remove

To execute magnolia command on remove DB action:

  • name command: preRemove or postRemove

  • preRemove is triggered before remove (delete) action

  • postRemove is triggered after remove (delete) action

  • put command definition in catalog that is named based on the database entity for which we want to trigger command

Example
'commenting-core':
  'commands':
    'comment':
      'postRemove':
        'class': 'info.magnolia.module.mail.commands.MailCommand' (1)
1 Sends an email message when a comment is deleted from the database.

Templating functions: commfn

A set of templating functions is exposed as commfn to allow developers use it in templates. This set of functions provides a set of methods to work with comments such as: liking a comment, reporting Abuse, disliking comments, etc,.

comments

Return a list of comments that match the search criteria.

Method signature

List<Comments> comments(String mgnlWorkspace, String mgnlUuid, Integer limit, Integer offset, Long parent, String sort)

Returns

List<Comments>

Usage
[#assign commentsList= commfn.comments("website","b06b82a2-74b0-4994-8015-028c4fd60716",15,0,15,'created asc')]

Arguments

All arguments are required unless otherwise noted.

Argument Description

mgnlWorkspace

The workspace you are working on.

The function retrieves item´s comments from this workspace.

mgnlUuid

The UUID of the item from where you want to get the comments.

limit

Number of results to return.

offset

Starting number of the rows to be returned.

sort

Sort parameter in form (ie: "created asc", "created desc" or "modified desc")

parent

ParentId of the comment.

optional

This option allows threaded comments.

comment

Return a specific comment by calling its unique ID.

Method signature

Comment comment(long commentId)

Returns

Comment

Usage
[#assign comment= commfn.comment(11)]
${comment.text}

Arguments

All arguments are required unless otherwise noted.

Argument Description

commentId

The unique id of the comment.

Deactivate ebeans log

Add the following to your log4js.xml file to deactivate the ebeans log.

<!-- Ebean -->
<logger name="io.ebean.SQL" level="INFO"/>
<logger name="io.ebean.TXN" level="INFO"/>
<logger name="io.ebean.SUM" level="INFO"/>
<logger name="io.ebean.QUERY" level="INFO"/>
<logger name="io.ebean.BEAN" level="INFO"/>
<logger name="io.ebean.COLL" level="INFO"/>
<logger name="io.ebean.NATKEY" level="INFO"/>

Changelog

Version Notes

1.1.4

Changelog

1.1.3

Changelog

1.1.2

Changelog

1.1.1

1.1
Feedback

Incubators

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Commenting module docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules