CAPTCHA API
 | API to generate and validate CAPTCHAs. |
| Type | JAR |
| Category | API |
| Developed by | |
| Rating | |
| License | GNU Lesser General Public License 2.1 |
| Bundled With | XWiki Standard (XWiki 10.8RC1+) |
| Compatibility | XWiki 10.8RC1+ |
Table of contents
Description
The main thing you need, when using a CAPTCHA, is to be able to display the CAPTCHA inside your form, so that the human user can solve it and to be able to validate the user's response, on the server side.
To get the default CAPTCHA (i.e. the one configured using the CAPTCHA Application), all you need to do is:
If you always want a specific implementation (not recommended), ignoring the configured one, but as long as it is installed on the XWiki instance:
## e.g.
$services.captcha.jcaptcha
## or
$services.captcha.recaptcha
Finally, to display the CAPTCHA:
Once the user submits your form, together with their answer to the proposed CAPTCHA, you need to validate it:
{{error}}Hey! We don't serve their kind here! (http://starwars.wikia.com/wiki/Anti-droid_sentiment){{/error}}
#end
Both display and validate operations also accept an optional parameters map, useful when you want to go beyond the configured parameters or even the configured default CAPTCHA in your form. Example:
Just make sure that, when using custom parameters on the display, you use the same parameters for the validation as well, or the user's answer might not validate correctly:
For other API methods, see the CaptchaScriptService.
Implementing your own CAPTCHA
Components you will need:
- A Captcha component implementation. It is recommended to extend the AbstractCaptcha (example) base class which simplifies things by adding some simple conventions:
- A Displayer document (example) that will render the CAPTCHA
- When evaluating the Displayer, the script context will contain a captchaParameters map that will be holding the CAPTCHA's configuration parameters, as read from the configuration document, including possible default values where it's the case (i.e. nothing specified in the configuration document)
- The Displayer's JavaScript, if it has any, will have to re-evaluate whenever the xwiki:captcha:reloaded event will be triggered (example), signaling that the CAPTCHA has been reloaded (e.g. by some AJAX call)
- A ConfigurationClass that will define the CAPTCHA's configuration properties
- A Configuration document that will hold the CAPTCHA's configuration
- An Administration document that will present the CAPTCHA's configuration, when the CAPTCHA is enabled. It will implement the org.xwiki.captcha UIXP (example).
- A Translations document (example) that provides, at minimum, the text the CAPTCHA's name (i.e. when enabling it in Administration).
- A Displayer document (example) that will render the CAPTCHA
Reference implementations:
- https://github.com/xwiki-contrib/captcha-recaptcha
- https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-captcha/xwiki-platform-captcha-jcaptcha
Prerequisites & Installation Instructions
We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).
You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.
Dependencies
Dependencies for this extension (org.xwiki.platform:xwiki-platform-captcha-api 16.10.1):
- org.xwiki.commons:xwiki-commons-component-api 16.10.1
- org.xwiki.commons:xwiki-commons-script 16.10.1
