Replace the old NOTES.txt and PRINCIPLES.txt with the Sphinx versions. Fix Captcha title.
svn path=/plone.app.discussion/trunk/; revision=36998
This commit is contained in:
Timo Stollenwerk
@@ -1,59 +0,0 @@
|
||||
=============================================
|
||||
plone.app.discussion architectural principles
|
||||
=============================================
|
||||
|
||||
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 should be 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
|
||||
All discussion item objects should be 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
|
||||
|
||||
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 should be
|
||||
fired when discussion items are added, removed, or modified.
|
||||
@@ -0,0 +1,59 @@
|
||||
========================
|
||||
Architectural Principles
|
||||
========================
|
||||
|
||||
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.
|
||||
@@ -1,5 +1,5 @@
|
||||
Captcha Design Notes
|
||||
====================
|
||||
Captcha Plugin Architecture
|
||||
===========================
|
||||
|
||||
This document contains design notes for the plone.app.discussion Captcha plugin
|
||||
architecture.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
=================================
|
||||
plone.app.discussion design notes
|
||||
=================================
|
||||
============
|
||||
Design Notes
|
||||
============
|
||||
|
||||
This document contains design notes for plone.app.discussion.
|
||||
|
||||
@@ -8,12 +8,12 @@ Storage and traversal
|
||||
---------------------
|
||||
|
||||
For each content item, there is a Conversation object stored in annotations.
|
||||
This can be traversed to via the ++comments++ namespace, but also fetched
|
||||
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/++comments++/123 retrieves
|
||||
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
|
||||
@@ -42,8 +42,8 @@ Factories
|
||||
|
||||
Comments should always be created via the 'Discussion Item' IFactory utility.
|
||||
Conversations should always be obtained via the IConversation adapter (even
|
||||
the ++comments++ namespace should use this). This makes it possible to replace
|
||||
conversations and comments transparently.
|
||||
the ++conversation++ namespace should use this). This makes it possible to
|
||||
replace conversations and comments transparently.
|
||||
|
||||
The Comment class
|
||||
-----------------
|
||||
@@ -150,20 +150,18 @@ an auto-moderation 'white-list', e.g. by email address or username.
|
||||
Forms and UI
|
||||
------------
|
||||
|
||||
The basic commenting display/reply form should be placed in a viewlet.
|
||||
The basic commenting display/reply form is placed in a viewlet.
|
||||
|
||||
Ideally, the reply form should be inline, perhaps revealed with JavaScript
|
||||
if enabled. This allows full contextualisation of replies. The current
|
||||
solution, with a separate form that shows some context, is brittle and
|
||||
over-complicated.
|
||||
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.
|
||||
|
||||
If we support quoting of comments in replies, we can load the text to quote
|
||||
using JavaScript as well.
|
||||
Since we rely on JavaScript for the reply form creation, the reply button is
|
||||
removed for nonJavaScript enabled browsers.
|
||||
|
||||
As a fall-back for non-JavaScript enabled browsers, it is probably OK not to
|
||||
support quoting and/or viewing of context, e.g. the user is taken to a standalone
|
||||
'comment reply' form.
|
||||
|
||||
All actual forms should be handled using z3c.form and plone.z3cform's
|
||||
ExtensibleForm support. This makes it possible to plug in additional fields
|
||||
declaratively, e.g. to include spam protection.
|
||||
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.
|
||||
Reference in New Issue
Block a user