Changeset 7306

Timestamp:

7 Dec 2011, 16:30:56 (13 years ago)

Author:

uli

Message:

Tell a bit about ReCaptcha?.

File:

• main/waeup.sirp/trunk/src/waeup/sirp/browser/captcha.py (modified) (4 diffs)

main/waeup.sirp/trunk/src/waeup/sirp/browser/captcha.py

@@ -245 +245 @@
     http://www.google.com/recaptcha.
 
-    ReCaptcha is widely used and adopted in web applications
+    ReCaptcha is widely used and adopted in web applications. See the
+    above web page to learn more about recaptcha.
+
+    Basically, it generates a captcha box in a page loaded by a
+    client. The client can then enter a solution for a challenge
+    picture (or audio file) and send the solution back to our server
+    along with the challenge string generated locally on the client.
+
+    This component then verifies the entered solution deploying the
+    private key set by asking a verification server. The result (valid
+    or invalid solution) is then returned to any calling component.
+
+    As any captcha-component, :class:`ReCaptcha` can be used by any
+    other component that wants to display/verify captchas.
+
+    To incorporate captcha usage in a view, page, or viewlet, the
+    following steps have to be performed:
+
+    * get the currently site-wide selected captcha type by doing::
+
+        mycaptcha = getUtility(ICaptchaChooser).getCaptcha()
+
+    * if you want a specific captcha type (like ReCaptcha)::
+
+        mycaptcha = getUtility(ICaptcha, name='ReCaptcha')
+
+    Now, as you have a captcha, you can verify sent data by doing::
+
+        result = mycaptcha.verify(self.request)
+
+    where ``self.request`` should be the sent HTTP request and
+    ``result`` will be an instance of class:``CaptchaResponse``. The
+    response will contain an error code (``result.error_code``) that
+    might be ``None`` but can (and should) be passed to the
+    :meth:``display`` method to display error messages in the captcha
+    box. The error code is most probably not a human readable string
+    but some code you shouldn't rely upon.
+
+    All this could be done in the ``update()`` method of a view, page,
+    or viewlet.
+
+    To render the needed HTML code, you can deploy the
+    :meth:`display`` method of ``mycaptcha``.
     """
 
@@ -262 +304 @@
 
     def verify(self, request):
+        """Grab challenge/solution from HTTP request and verify it.
+
+        Verification happens against recaptcha remote API servers. It
+        only happens, when really a solution was sent with the
+        request.
+
+        Returns a :class:`CaptchaResponse` indicating that the
+        verification failed or succeeded.
+        """
         form = getattr(request, 'form', {})
         solution=form.get(self.sol_field, None)
         challenge=form.get(self.chal_field, None)
         if not challenge or not solution:
-            # maybe first display of the captcha: not a valid solution
-            # but no error code to prevent any error messages
+            # Might be first-time display of the captcha: not a valid
+            # solution but no error code to prevent any error
+            # messages. Skip further verification.
             return CaptchaResponse(
                 is_valid=False)
@@ -296 +348 @@
     def display(self, error_code=None):
         """Display challenge and input field for solution as HTML.
+
+        Returns the HTML code to be placed inside an existing ``<form>``
+        of your page. You can add other fields and should add a submit
+        button to send the form.
+
+        The ``error_code`` can be taken from a previously fetched
+        :class:``CaptchaResponse`` instance (as returned by
+        :meth:``verify``). If it is not ``None``, it might be
+        displayed inside the generated captcha box (in human readable
+        form).
         """
         error_param = ''
@@ -326 +388 @@
 
 class CaptchaTestPage(SIRPPage):
+    # A test page to see a captcha in action
     grok.name('captcha')
     grok.context(IUniversity)