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

This module offers commenting features and the possibility of like or dislike the comments, moderate them or mark as author´s favourite. The commenting module provides a Rest API for comments and a Content App called comments to view comments of an item. It uses an external database to store the commenting data.

Installation

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

<dependency>
  <groupId>info.magnolia.commenting</groupId>
  <artifactId>magnolia-commenting-app</artifactId>
  <version>${commentingVersion}</version>
</dependency>
<dependency>
  <groupId>info.magnolia.commenting</groupId>
  <artifactId>magnolia-commenting-rest</artifactId>
  <version>${commentingVersion}</version>
</dependency>


Add the chosen database JDBC drivers.

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>

Versions

1.1Magnolia 6.2
1.0Magnolia 6.1.4/6.2 (old UI)

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

Usage

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

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

Troubleshooting

If you have an error like: 

 "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, like described bellow:

datasource:
	username: user
	password: password
	url: jdbc:mysql://127.0.0.1:3306/comments?serverTimezone=Europe/Madrid
	driver: com.mysql.cj.jdbc.Driver
	migration:
		path: dbmigration/mysql
		run: true


PostreSQL:

/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

This module does not create a database.

The database must exist and a user having the CREATE/DROP/ALTER rights on that database must be defined.

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 you have to create into commenting-rest module the following configuration: 

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

Cache

Be aware on Public instances, anonymous comments will be cached on Magnolia by default. To prevent caching, add an entry in cache's excludes section for URIs starting with "/.rest/commenting"

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: 

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

In this app you can:

  • View comments(and their detail)
  • Delete comments
  • Moderate comment, which is "Report Abuse" action
  • Author choice: fav 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: {}

Rest API

API Path: /v1/commenting

Method

Path

Description

GET/comments/{workspace}/{jcrId}

Return all the comments of a given JCR node with possibility to paginate the results
Query string:
- limit: Limit the number of results
- offset: Index to return the results from
- parent: Parent comment id
- sort: Field to use for sorting and the order (ie: sort=date:asc, sort=date:desc)

GET/comment/{commentId}Return the given comment
POST/commentPost the comment contained in the body (json representation of the comment)
POST/report/{commentId}Flag the comment as an abuse (no body)
POST/author/{commentId}Flag the comment as a author choice (no body)
POST/like/{commentId}Like the given comment (no body)
POST/unlike/{commentId}Unlike the given comment (no body)
POST/rate/{commentId}Rate the given comment (value field in the body)
PUT/commentUpdate a comment contained in the body (json representation of the comment)
DELETE/comment/{commentId}Delete the given comment

REST API

GET

Get comments per workspace and UUID

Request URL

/.rest/commenting/v1/comments/{workspace}/{uuid}

Parameters

Parameter

Description

Parameter type

Data type

workspace

required

The node workspace.

path

string

uuid

required

The node UUID.

path

string

limitMax number of comments returnedqueryinteger
offsetIndex of the first comment to be returnedqueryinteger
parentThe parent comment idquerylong
sortThe name of the field to use for sortingquerystring


Get comment per id

Request URL

/.rest/commenting/v1/comment/{commentId}

Parameters

Parameter

Description

Parameter type

Data type

commentId

required

The comment id.

path

string


POST

Create a comment

Request URL

/.rest/commenting/v1/comment

Parameters

Parameter

Description

Parameter type

Data type

body

required

Request body format: JSON or XML..

body

string

Examples
body
{
  "mgnlWorkspace": "website",
  "mgnlId": "11ae4546-b7e0-4868-86ba-76809ef085cb",
  "text": "example rest 3",
  "authorChoice": false,
  "abuseReport": false,
  "rating": 0,
  "userName": "username",
  "userEmail": "useremail"

}

You can call with Authorisation Basic(with username and password, so the userName sent in the POST call will be the logged user) or call without Authorisation and the comment will be anonymous(whenever anonymous comments are allowed as described before)

Create a threaded comment

Request URL

/.rest/commenting/v1/comment

Parameters

Parameter

Description

Parameter type

Data type

body

required

Request body format: JSON or XML..

body

string

Examples
body
{
  "mgnlWorkspace": "website",
  "mgnlId": "11ae4546-b7e0-4868-86ba-76809ef085cb",
  "text": "example rest 3",
  "authorChoice": false,
  "abuseReport": false,
  "rating": 0,
  "userName": "username",
  "userEmail": "useremail",
  "parentId": 1

}

As we have seen before you can call with anonymous or logged user, the important thing of threaded comments is the body parameter "parentId", while parentId is the id of the parent comment. 

Report an abuse

Request URL

/.rest/commenting/v1/report/{commentId}

Parameters

Parameter

Description

Parameter type

Data type

commentId

required

The comment id.

path

string


Like a comment

Request URL

/.rest/commenting/v1/like/{commentId}

Parameters

Parameter

Description

Parameter type

Data type

commentId

required

The comment id.

path

string


Dislike a comment

Request URL

/.rest/commenting/v1/dislike/{commentId}

Parameters

Parameter

Description

Parameter type

Data type

commentId

required

The comment id.

path

string


Associate a rate to a comment

Request URL

/.rest/commenting/v1/rate/{commentId}

Parameters

Parameter

Description

Parameter type

Data type

commentId

required

The comment id.

path

string

value

required

The value of rating

forminteger
{
  "value": 5
}

DELETE

Delete a comment

Request URL

/.rest/commenting/v1/comment/{commentId}

Parameters

Parameter

Description

Parameter type

Data type

commentId

required

The comment id.

path

string


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: like a comment, report Abuse, dislike a comment, 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)

Arguments:

mgnlWorkspace

required

The workspace you are working on. The function retrieves item´s comments  from this workspace.

mgnlUuid

required

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

limit

required

Number of results to return

offset

required

Starting number of rows to be returned

parent

optional default is 0

ParentId of the comment. This option allows threaded comments.

sort

required

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

Returns:

List<Comments>

Usage:

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


comment

Return a specific comment by calling it's ID

Method signature:  Comment  comment(long commentId)

Arguments:

commentId

required

commentId id of the comment.

Returns: 

 Comment

Usage:

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


Deactivate ebean logs


log4j2.xml
<!-- 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

  • No labels