Captcha documentation updated (code examples included, etc).

svn path=/plone.app.discussion/trunk/; revision=37369
This commit is contained in:
Timo Stollenwerk 2010-06-21 09:11:45 +00:00
parent a702b2877e
commit 5f2daced20
2 changed files with 45 additions and 11 deletions

View File

@ -9,30 +9,36 @@ Introduction
------------ ------------
When a Captcha plugin (e.g. plone.formwidget.captcha or When a Captcha plugin (e.g. plone.formwidget.captcha or
plone.formwidget.recaptcha) is installed, plone.app.discussion plone.formwidget.recaptcha, collective.akismet) is installed,
extends the comment form with a Captcha field/widget and a Captcha validator. 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 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 installed that claims to provide the "plone.app.discussion-captcha" feature in
its configure.zcml file:: its configure.zcml file::
<configure ... <configure
xmlns:meta="http://namespaces.zope.org/meta"> xmlns:meta="http://namespaces.zope.org/meta"
xmlns:zcml="http://namespaces.zope.org/zcml">
<!-- Declare that plone.formwidget.captcha provides a Captcha field that <!-- Declare that plone.formwidget.captcha provides a Captcha field that
can be used by plone.app.discussion to add a Captcha field to comment can be used by plone.app.discussion to add a Captcha field to comment
forms. --> forms. -->
<meta:provides feature="plone.app.discussion-captcha" /> <meta:provides feature="plone.app.discussion-captcha" />
...
</configure> </configure>
For an example see: .. note::
https://svn.plone.org/svn/plone/plone.formwidget.captcha/trunk/plone/formwidget/captcha/configure.zcml Currently plone.formwidget.captcha, plone.formwidget.recaptcha, and
collective.akismet provide such a feature. If you want to write your own
Captcha plugin, it has to provide this feature as well.
Currently plone.formwidget.captcha and plone.formwidget.recaptcha provide such a .. seealso::
feature. If you want to write your own Captcha plugin, it has to provide this
feature as well. * https://svn.plone.org/svn/plone/plone.formwidget.captcha/trunk/plone/formwidget/captcha/meta.zcml
* https://svn.plone.org/svn/plone/plone.formwidget.recaptcha/trunk/plone/formwidget/recaptcha/meta.zcml
* https://svn.plone.org/svn/collective/collective.akismet/trunk/collective/akismet/meta.zcml
CaptchaExtender CaptchaExtender
@ -45,6 +51,10 @@ 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 have to override the update() method of the CaptchaExtender or write your own
CaptchaExtender class. CaptchaExtender class.
.. literalinclude:: ../../plone/app/discussion/browser/captcha.py
:language: python
:pyobject: CaptchaExtender
CaptchaValidator CaptchaValidator
---------------- ----------------
@ -64,3 +74,26 @@ 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 plone.app.discussion-captcha feature, see notes above). Second, we check which
Captcha solution is enabled in the discussion control panel and apply the Captcha solution is enabled in the discussion control panel and apply the
corresponding field validator. corresponding field validator.
The plone.app.discussion captcha validator always checks for a view with the
name of the captcha plugin. For instance, if plone.formwidget.captcha is enabled
it checks for a "captcha" view.
.. literalinclude:: ../../plone/app/discussion/browser/validator.py
:language: python
:pyobject: CaptchaValidator
.. Writing your own Captcha plugin
-------------------------------
If you want to write your own Captcha plugin, you have to add at least the
following things:
1) Add your Captcha plugin to the captcha_vocabulary (vocabularies.py)
2) Override the update() method of the CapchaExtender class (browser/captcha.py)
to show your own Captcha widget.
3) Override the validate() method of the CaptchaValidator class
(browser/validator.py) to use your own Captcha validator.

View File

@ -67,7 +67,8 @@ class CaptchaValidator(validator.SimpleFieldValidator):
raise WrongCaptchaCode raise WrongCaptchaCode
else: else:
return True return True
# Register Captcha validator for the Captcha field in the ICaptcha Form # Register Captcha validator for the Captcha field in the ICaptcha Form
validator.WidgetValidatorDiscriminators(CaptchaValidator, validator.WidgetValidatorDiscriminators(CaptchaValidator,
field=ICaptcha['captcha']) field=ICaptcha['captcha'])