Comments
Contents
Comments#
Changed in version Plone: 6.1
Discussion is disabled by default in Plone 6.1 and later. To enable discussion, see the Plone 6.1 upgrade guide section Discussion is a core add-on.
Discussion is a feature that allows your site visitors to comment on web pages for any content object.
Commenting can be enabled globally for specific content types and for single content objects.
When commenting is enabled on your content object, you can retrieve a list of all existing comments, add new comments, reply to existing comments, or delete a comment.
Listing Comments#
You can list the existing comment on a content object by sending a GET
request to the URL of the content object and appending /@comments
:
GET /plone/front-page/@comments HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i -X GET http://nohost/plone/front-page/@comments -H "Accept: application/json" --user admin:secret
http http://nohost/plone/front-page/@comments Accept:application/json -a admin:secret
requests.get('http://nohost/plone/front-page/@comments', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
The server will respond with a Status 200
and a batched list of all comments:
HTTP/1.1 200 OK
Content-Type: application/json
{
"@id": "http://localhost:55001/plone/front-page/@comments",
"items": [
{
"@id": "http://localhost:55001/plone/front-page/@comments/1400000000000000",
"@parent": null,
"@type": "Discussion Item",
"author_image": null,
"author_name": null,
"author_username": null,
"can_reply": true,
"comment_id": "1400000000000000",
"creation_date": "1995-07-31T13:45:00+00:00",
"in_reply_to": null,
"is_deletable": true,
"is_editable": true,
"modification_date": "1995-07-31T17:30:00+00:00",
"text": {
"data": "Comment 1",
"mime-type": "text/plain"
},
"user_notification": null
},
{
"@id": "http://localhost:55001/plone/front-page/@comments/1400000000000001",
"@parent": "http://localhost:55001/plone/front-page/@comments/1400000000000000",
"@type": "Discussion Item",
"author_image": null,
"author_name": null,
"author_username": null,
"can_reply": true,
"comment_id": "1400000000000001",
"creation_date": "1995-07-31T13:45:00+00:00",
"in_reply_to": "1400000000000000",
"is_deletable": true,
"is_editable": true,
"modification_date": "1995-07-31T17:30:00+00:00",
"text": {
"data": "Comment 1.1",
"mime-type": "text/plain"
},
"user_notification": null
}
],
"items_total": 2,
"permissions": {
"can_reply": true,
"view_comments": true
}
}
The following fields are returned.
@id
: Link to the current endpointitems
: a list of comments for the current resourceitems_total
: the total number of comments for the resourcebatching
: batching information
The items
attribute returns a list of comments.
Each comment provides the following fields.
@id
: hyperlink to the comment@parent
: (optional) the parent commentauthor_name
: the full name of the author of this commentauthor_username
: the username of the author of this commentcomment_id
: the comment ID uniquely identifies the commentin_reply_to
: the comment ID of the parent commentcreation_date
: when the comment was placedmodification_date
: when the comment was last updatedtext
: contains amime-type
andtext
attribute with the text of the comment. Defaultmime-type
istext/plain
.user_notification
: boolean value to indicate if the author of the comment requested notifications on replies
Adding a Comment#
To add a new comment to a content object, send a POST
request to the URL of the content object and append /@comments
to the URL.
The body of the request needs to contain a JSON structure with a text
attribute that contains the comment text:
POST /plone/front-page/@comments/ HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"text": "My comment"
}
curl -i -X POST http://nohost/plone/front-page/@comments/ -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"text": "My comment"}' --user admin:secret
echo '{
"text": "My comment"
}' | http POST http://nohost/plone/front-page/@comments/ Accept:application/json Content-Type:application/json -a admin:secret
requests.post('http://nohost/plone/front-page/@comments/', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'text': 'My comment'}, auth=('admin', 'secret'))
If the creation of the comment has been successful, the server will respond with a 204 No Content status and the URL of the newly created comment in the location header:
HTTP/1.1 204 No Content
Location: http://localhost:55001/plone/front-page/@comments/123456
Replying to a Comment#
To add a direct reply to an existing comment, send a POST
request to the URL of the comment
to which you want to reply.
The body of the request needs to contain a JSON structure with a text
attribute that contains the comment text:
POST /plone/front-page/@comments/123456 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"text": "My reply"
}
curl -i -X POST http://nohost/plone/front-page/@comments/123456 -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"text": "My reply"}' --user admin:secret
echo '{
"text": "My reply"
}' | http POST http://nohost/plone/front-page/@comments/123456 Accept:application/json Content-Type:application/json -a admin:secret
requests.post('http://nohost/plone/front-page/@comments/123456', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'text': 'My reply'}, auth=('admin', 'secret'))
If the creation of the comment has been successful, the server will respond with a 204 No Content status and the URL of the newly created comment in the location header:
HTTP/1.1 204 No Content
Location: http://localhost:55001/plone/front-page/@comments/123456
Updating a Comment#
Note
The permission to update a comment is, by default, only granted to the creater (owner role) of the comment.
An existing comment can be updated by sending a PATCH
request to the URL of the comment.
The request body needs to contain a JSON structure with at least a text
attribute:
PATCH /plone/front-page/@comments/123456 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"text": "My NEW comment"
}
curl -i -X PATCH http://nohost/plone/front-page/@comments/123456 -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"text": "My NEW comment"}' --user admin:secret
echo '{
"text": "My NEW comment"
}' | http PATCH http://nohost/plone/front-page/@comments/123456 Accept:application/json Content-Type:application/json -a admin:secret
requests.patch('http://nohost/plone/front-page/@comments/123456', headers={'Accept': 'application/json', 'Content-Type': 'application/json'}, json={'text': 'My NEW comment'}, auth=('admin', 'secret'))
The server will respond with a 204 No Content response and a location header with the comment URL when the comment has been updated successfully:
HTTP/1.1 204 No Content
Location: http://localhost:55001/plone/front-page/@comments/123456
Deleting a Comment#
An existing comment can be deleted by sending a DELETE
request to the URL of the comment.
Note
Deleting a comment will, by default, also delete all existing replies to that comment.
DELETE /plone/front-page/@comments/123456 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl -i -X DELETE http://nohost/plone/front-page/@comments/123456 -H "Accept: application/json" --user admin:secret
http DELETE http://nohost/plone/front-page/@comments/123456 Accept:application/json -a admin:secret
requests.delete('http://nohost/plone/front-page/@comments/123456', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))
When the comment has been deleted successfully, the server will respond with a 204 No Content response:
HTTP/1.1 204 No Content