Comments
Contents
Comments#
Plone offers to users a feature to post comments on any content object with plone.app.discussion
.
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
:
http
GET /plone/front-page/@comments HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl
curl -i -X GET http://nohost/plone/front-page/@comments -H "Accept: application/json" --user admin:secret
httpie
http http://nohost/plone/front-page/@comments Accept:application/json -a admin:secret
python-requests
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:
http
POST /plone/front-page/@comments/ HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"text": "My comment"
}
curl
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
httpie
echo '{
"text": "My comment"
}' | http POST http://nohost/plone/front-page/@comments/ Accept:application/json Content-Type:application/json -a admin:secret
python-requests
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:
http
POST /plone/front-page/@comments/123456 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"text": "My reply"
}
curl
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
httpie
echo '{
"text": "My reply"
}' | http POST http://nohost/plone/front-page/@comments/123456 Accept:application/json Content-Type:application/json -a admin:secret
python-requests
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:
http
PATCH /plone/front-page/@comments/123456 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json
{
"text": "My NEW comment"
}
curl
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
httpie
echo '{
"text": "My NEW comment"
}' | http PATCH http://nohost/plone/front-page/@comments/123456 Accept:application/json Content-Type:application/json -a admin:secret
python-requests
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.
http
DELETE /plone/front-page/@comments/123456 HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
curl
curl -i -X DELETE http://nohost/plone/front-page/@comments/123456 -H "Accept: application/json" --user admin:secret
httpie
http DELETE http://nohost/plone/front-page/@comments/123456 Accept:application/json -a admin:secret
python-requests
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