API/Interfaces

The conversation and replies adapters.

The conversation is responsible for storing all comments. It provides a dict-like API for accessing comments, where keys are integers and values are IComment objects. It also provides features for finding comments quickly.

The IReplies adapter provides an API for finding and manipulating the comments directly in reply to a particular comment (implemented by the CommentReplies adpater) or at the top level of the conversation (implemented by the ConversationReplies adapter).

interface plone.app.discussion.interfaces.IConversation

Extends: zope.interface.common.mapping.IIterableMapping

A conversation about a content object.

This is a persistent object in its own right and manages all comments.

The dict interface allows access to all comments. They are stored by long integer key, in the order they were added.

Note that __setitem__() is not supported - use addComment() instead. However, comments can be deleted using __delitem__().

To get replies at the top level, adapt the conversation to IReplies.

The conversation can be traversed to via the ++comments++ namespace. For example, path/to/object/++comments++/123 retrieves comment 123.

The __parent__ of the conversation (and the acquisition parent during traversal) is the content object. The conversation is the __parent__ (and acquisition parent) for all comments, regardless of threading.

__delitem__(key)

Delete the comment with the given key. The key is a long id.

last_comment_date

Date of the most recent comment

total_comments

Total number of comments on this item

getComments(start=0, size=None)

Return an iterator of comment objects for rendering.

The ‘start’ parameter is the id of the comment from which to start the batch. If no such comment exists, the next higher id will be used. This means that you can use max key from a previous batch + 1 safely.

The ‘size’ parameter is the number of comments to return in the batch.

The comments are returned in creation date order, in the exact batch size specified.

enabled()

Returns True if discussion is enabled for this conversation.

This method checks five different settings in order to figure out if discussion is enable on a specific content object:

1. Check if discussion is enabled globally in the plone.app.discussion registry/control panel.
2. If the current content object is a folder, always return False, since we don’t allow comments on a folder. This setting is used to allow/ disallow comments for all content objects inside a folder, not for the folder itself.
3. Check if the allow_discussion boolean flag on the content object is set. If it is set to True or False, return the value. If it set to None, try further.
4. Traverse to a folder with allow_discussion set to either True or False. If allow_discussion is not set (None), traverse further until we reach the PloneSiteRoot.
5. Check if discussion is allowed for the content type.

getThreads(start=0, size=None, root=0, depth=None)

Return a batch of comment objects for rendering.

The ‘start’ parameter is the id of the comment from which to start the batch. If no such comment exists, the next higher id will be used. This means that you can use max key from a previous batch + 1 safely. This should be a root level comment.

The ‘size’ parameter is the number of threads to return in the batch. Full threads are always returned (although you can stop consuming the iterator if you want to abort).

‘root’, if given, is the id of the comment to which reply threads will be found. ‘root’ itself is not included. If not given, all threads are returned.

If ‘depth’ is given, it can be used to limit the depth of threads returned. For example, depth=1 will return only direct replies.

Comments are returned as an iterator of dicts with keys ‘comment’, the comment, ‘id’, the comment id, and ‘depth’, which is 0 for top-level comments, 1 for their replies, and so on. The list is returned in depth-first order.

addComment(comment)

Adds a new comment to the list of comments, and returns the comment id that was assigned. The comment_id property on the comment will be set accordingly.

commentators

The set of unique commentators (usernames)

interface plone.app.discussion.interfaces.IReplies

Extends: zope.interface.common.mapping.IIterableMapping

A set of related comments in reply to a given content object or another comment.

Adapt a conversation or another comment to this interface to obtain the direct replies.

__delitem__(key)

Delete the comment with the given key. The key is a long id.

addComment(comment)

Adds a new comment as a child of this comment, and returns the comment id that was assigned. The comment_id property on the comment will be set accordingly.

interface plone.app.discussion.interfaces.IComment

A comment.

Comments are indexed in the catalog and subject to workflow and security.

author_username

Name

modification_date

Modification date

title

Subject

author_email

Email

text

Comment

portal_type

Portal type

comment_id

A comment id unique to this conversation

author_name

Name

creation_date

Creation date

mime_type

MIME type

__name__

Name

in_reply_to

Id of comment this comment is in reply to

creator

Author name (for display)

__parent__

Conversation