From 7f28f2773a55a6d011bbac28e50c06fc75f527ed Mon Sep 17 00:00:00 2001
From: Timo Stollenwerk <timo@zmag.de>
Date: Fri, 4 Jun 2010 10:57:57 +0000
Subject: [PATCH] Design notes for the Captcha plugin architecture added.

svn path=/plone.app.discussion/trunk/; revision=36993
---
 CHANGES.txt                               |  3 +
 plone/app/discussion/browser/captcha.py   |  4 ++
 plone/app/discussion/browser/captcha.txt  | 67 +++++++++++++++++++++++
 plone/app/discussion/browser/validator.py |  2 +
 4 files changed, 76 insertions(+)
 create mode 100644 plone/app/discussion/browser/captcha.txt

diff --git a/CHANGES.txt b/CHANGES.txt
index ad7a59a..7c9a04a 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -4,6 +4,9 @@ Changelog
 1.0b5 (unreleased)
 ------------------
 
+* Design notes for the Captcha plugin architecture added.
+  [timo]
+
 * Make IDiscussionLayer inherit from Interface again. Remove IDefaultPloneLayer,
   since Plone 4.0b1 and plone.theme 2.0b1 are out now.
   [timo]
diff --git a/plone/app/discussion/browser/captcha.py b/plone/app/discussion/browser/captcha.py
index bc32fc2..0422729 100644
--- a/plone/app/discussion/browser/captcha.py
+++ b/plone/app/discussion/browser/captcha.py
@@ -1,3 +1,7 @@
+# -*- coding: utf-8 -*-
+
+# Captcha validator, see captcha.txt for design notes.
+
 from persistent import Persistent
 
 from Products.CMFCore.utils import getToolByName
diff --git a/plone/app/discussion/browser/captcha.txt b/plone/app/discussion/browser/captcha.txt
new file mode 100644
index 0000000..dbc0135
--- /dev/null
+++ b/plone/app/discussion/browser/captcha.txt
@@ -0,0 +1,67 @@
+====================
+Captcha Design Notes
+====================
+
+This document contains design notes for the plone.app.discussion Captcha plugin
+architecture.
+
+
+Introduction
+------------
+
+When a Captcha plugin (e.g. plone.formwidget.captcha or 
+plone.formwidget.recaptcha) is installed, plone.app.discussion 
+extends the comment form with a Captcha field/widget and a Captcha validator.
+
+The form extender and validator are only registered if there is a plugin 
+installed that claims to provide the "plone.app.discussion-captcha" feature in 
+its configure.zcml file::
+
+    <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 an example see:
+
+https://svn.plone.org/svn/plone/plone.formwidget.captcha/trunk/plone/formwidget/captcha/configure.zcml
+
+Currently plone.formwidget.captcha and plone.formwidget.recaptcha provide such a
+feature. If you want to write your own Captcha plugin, it has to provide this 
+feature as well.
+
+    
+CaptchaExtender
+---------------
+
+The CaptchaExtender class extends the comment form with a Captcha field and
+widget. The CaptchaExtender currently uses either the CaptchaFieldWidget from
+plone.formwidget.captcha or the ReCaptchaFieldWidget from 
+plone.formwidget.recaptcha. If you want to write your own Captcha solution, you
+have to override the update() method of the CaptchaExtender or write your own
+CaptchaExtender class.
+
+
+CaptchaValidator
+----------------
+
+The CaptchaValidator class provides custom versions of the 
+plone.formwidget.captcha and the plone.formwidget.recaptcha validators. It does 
+this, because we want to be able to have more than one Captcha solution 
+installed in one Plone instance. We also want to be able to easily switch 
+between different Captcha implementations inside a single Plone instance. 
+
+Therefore we have to check which Captcha solution is enabled in the discussion 
+control panel and use only the selected Captcha validator. It is not enough to 
+check if a Captcha plugin is just installed, because there could be more than 
+one.
+
+We do two checks. First we check for a suitable Captcha solution (check for the 
+plone.app.discussion-captcha feature, see notes above). Second, we check which 
+Captcha solution is enabled in the discussion control panel and apply the 
+corresponding field validator.
diff --git a/plone/app/discussion/browser/validator.py b/plone/app/discussion/browser/validator.py
index 7e775ee..ca0a722 100644
--- a/plone/app/discussion/browser/validator.py
+++ b/plone/app/discussion/browser/validator.py
@@ -1,5 +1,7 @@
 # -*- coding: utf-8 -*-
 
+# Captcha validator, see captcha.txt for design notes.
+
 from Acquisition import aq_inner
 
 from z3c.form import validator