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).
-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.
-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.
-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:
-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.
-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.
-A comment.
-Comments are indexed in the catalog and subject to workflow and security.
-This document outlines architectural principles used in the design of -plone.app.discussion.
----
-- Discussion items have a portal_type
-- This makes it easier to search for them and manage them using existing -CMF and Plone UI constructs.
-- Discussion items are cataloged
-- It is possible to search for discussion items like any other type of -content.
-- Discussion items are subject to workflow and permission
-- Moderation, anonymous commenting, and auto approve/reject should be -handled using workflow states, automatic and manual transitions, and -permissions.
-- Discussion items are light weight objects
-- Discussion item objects are as light weight as possible. Ideally, a -discussion item should be as lightweight as a catalog brain. This may mean -that we forego convenience base classes and re-implement certain interfaces. -Comments should not provide the full set of dublin core metadata, though -custom indexers can be used to provide values for standard catalog indexes.
-- Optimise for retrival speed
-- HTML filtering and other processing should happen on save, not on render, -to make rendering quick.
-- Settings are stored using plone.registry
-- Any global setting should be stored in plone.registry records.
-- Forms are constructed using extensible z3c.form forms
-- This allows plugins (such as spam protection algorithms) to provide -additional validation. It also allows integrators to write add-ons that add -new fields to the comment form.
-- Discussion items are stored in a BTree container
-- This allows faster lookup and manipulation.
-- Discussion items are accessed using a dict-like interface
-- This makes iteration and manipulation more natural. Even if comments are -not stored threaded, the dict interface should act as if they are, i.e. -calling items() on a comment should return the replies to that comment -(in order).
-- Discussion items are retrieved in reverse creation date order
-- Discussion items do not need to support explicit ordering. They should -always be retrieved in reverse creation date order (most recent for). -They can be stored with keys so that this is always true.
-- Discussion items do not need readable ids
-- Ids can be based on the creation date.
-- Discussion items send events
-- The usual zope.lifecycleevent and zope.container events are fired when -discussion items are added, removed, or modified.
-
This document contains design notes for the plone.app.discussion Captcha plugin -architecture. It also explains how to write your own Captcha plugin (???).
-Currently there are two plugins that work with plone.app.discussion:
----
-- plone.formwidget.captcha
-- plone.formwidget.recaptcha
-
Add this to your configure.zcml:
-<configure ...
- xmlns:meta="http://namespaces.zope.org/meta">
- <!-- Declare that plone.formwidget.captcha provides a Captcha field that
- can be used by plone.app.discussion to add a Captcha field to comment
- forms. -->
- <meta:provides feature="plone.app.discussion-captcha" />
-
- ...
-</configure>
-For examples have a look at plone.formwidget.captcha
- -This document contains design notes for plone.app.discussion.
-For each content item, there is a Conversation object stored in annotations. -This can be traversed to via the ++conversation++ namespace, but also fetched -via an adapter lookup to IConversation.
-The conversation stores all comments related to a content object. Each -comment has an integer id (also representable as a string, to act as an OFS -id and allow traversal). Hence, traversing to obj/++conversation++/123 retrieves -the comment with id 123.
-Comments ids are assigned in order, so a comment with id N was posted before -a comment with id N + 1. However, it is not guaranteed that ids will be -incremental. Ids must be positive integers - 0 or negative numbers are not -allowed.
-Threading information is stored in the conversation: we keep track of the -set of children and the parent if any comment. Top-level comments have a -parent id of 0. This information is managed by the conversation class when -comments are manipulated using a dict-like API.
-Note that the __parent__/acquisition parent of an IComment is the -IConversation, and the __parent__/acquisition parent of an IConversation is -the content object.
-Manipulating the IConversation object should fire the usual IObjectAddedEvent -and IObjectRemovedEvent events. The UI may further fire IObjectCreatedEvent -and IObjectModifiedEvent for comments.
-Comments should always be created via the ‘Discussion Item’ IFactory utility. -Conversations should always be obtained via the IConversation adapter (even -the ++conversation++ namespace should use this). This makes it possible to -replace conversations and comments transparently.
-The inheritance tree for DiscussionItem is shown below. Classes we want to -mix in and interface we want to implement in the Comment class are marked -with [x].
----
-- [ ] DiscussionItem
-- -
-
-- [ ] Document
-- -
-
-- [ ] PortalContent = [ ] IContentish
-- -
[ ] DynamicType = [ ] IDynamicType -[ ] CMFCatalogAware = [ ] <no interface> -[ ] SimpleItem = [ ] ISimpleItem
----
-- [ ] Item [ ]
-- [?] Base = [ ] <no interface> -[ ] Resource = [ ] <no interface> -[ ] CopySource = [ ] ICopySource -[ ] Tabs = [ ] <no interface> -[x] Traversable = [ ] ITraversable -[ ] Element = [ ] <no interface> -[x] Owned = [ ] IOwned -[ ] UndoSupport = [ ] IUndoSupport
-[ ] Persistent [ ] -[ ] Implicit [ ] -[x] RoleManager = [ ] IRoleManager
--[ ] RoleManager = [ ] IPermissionMappingSupport-- [ ] DefaultDublinCoreImpl = [ ] IDublinCore
-- -
-[ ] ICatalogableDublinCore -[ ] IMutableDublinCore-[ ] PropertyManager = [ ] IPropertyManager
-
Thus, we want:
----
-- -
-
-- Traversable, to get absolute_url() and friends
-- -
-
-- this requires a good acquisition chain at all times
-- -
-
-- Acquisition.Explicit, to support acquisition
-- -
-
-- we do not want implicit acquisition
-- -
Owned, to be able to track ownership
-- -
RoleManager, to support permissions and local roles
-
We also want to use a number of custom indexers for most of the standard -metadata such as creator, effective date etc.
-Finally, we’ll need event handlers to perform the actual indexing.
-Discussion can be enabled per-type and per-instance, via values in the FTI -(allow_discussion) and on the object. These will remain unchanged. The -IConversation object’s ‘enabled’ property should consult these.
-Global settings should be managed using plone.registry. A control panel -can be generated from this as well, using the helper class in -plone.app.registry.
-Note that some settings, notably those to do with permissions and workflow, -will need to be wired up as custom form fields with custom data mangers -or similar.
-Where possible, we should use existing permissions:
----
-- View
-- Reply to Item
-- Modify Portal Content
-- Request Review
-
In addition, we’ll need a ‘Moderator’ role and a moderation permission,
----
-- Moderate comment
-- Bypass moderation
-
To control whether Anonymous can post comments, we manage the ‘Reply to Item’ -permission. To control whether moderation is required for various roles, we -could manage the ‘Bypass moderation’ permission.
-These could work in a workflow like this:
----
-- -
-
-- –> [posted] – {publish} –> [published]–> *
-- -
--^- -+—– {auto-publish} —–+ -| | -+—– {auto-moderate} —-+
-
The ‘posted’ state is the initial state. ‘published’ is the state where the -comment is visible to non-reviewers.
-The ‘publish’ transition would be protected by the ‘Moderate comment’ -permission. We could have states and transition for ‘rejected’, etc, but it -is probably just as good to delete comments that are rejected.
-The ‘auto-publish’ transition would be an automatic transition protected by -the ‘Bypass moderation’ permission.
-The ‘auto-moderate’ transition would be another automatic transition protected -by an expression (e.g. calling a view) that returns True if the user is on -an auto-moderation ‘white-list’, e.g. by email address or username.
-The basic commenting display/reply form is placed in a viewlet.
-The reply form is dynamically created right under the comment when the user hits -the reply button. To do so, we copy the standard comment form with a jQuery -function. This function sets the form’s hidden in_reply_to field to the id of -the comment the user wants to reply to. This also makes is possible to use -z3c.form validation for the reply forms, because we can uniquely identify the -a reply form request and return the reply form with validation errors.
-Since we rely on JavaScript for the reply form creation, the reply button is -removed for nonJavaScript enabled browsers.
-The comment form uses z3c.form and plone.z3cform’s ExtensibleForm support. This -makes it possible to plug in additional fields declaratively, e.g. to include -SPAM protection.
-Contents:
- -- Please activate JavaScript to enable the search - functionality. -
-- From here you can search these documents. Enter your search - words into the box below and click "search". Note that the search - function will automatically search for all of the words. Pages - containing fewer words won't appear in the result list. -
- - -