CAPTCHA taglib (for forms)

The captcha module enables the developer to easily integrate CAPTCHA functionality into existent forms. For this reason, the taglib included in the captcha module must be placed within the desired form and the front controller action used to deliver the captcha image needs to be configured. Moreover, the taglib implementation gives you an example of how the <form:addtaglib /> tag can be used to extend form functionality.

The following chapters describe how to include the captcha tag into your form.

Starting with release 1.16 an alternative implementation is available to protect forms. Details can be read about under ReCaptcha. It supports Google's CAPTCHA concept and both protects your pages from being requested by bots and helps to improve the OCR software used to digitize books.

1. Configuration of the front controller action

As mentioned above, the delivery of the captcha image is done by a front controller action included in the module. To make sure, that the image is served correctly, the project must be configured using the front controller. If your project uses the page controller, the bootstrap file must be adapted. In case, your index.php contains

PHP code
include_once('./apps/core/pagecontroller/pagecontroller.php'); $page = new Page(); $page->loadDesign('sites::demosite::pres::templates','website'); echo $page->transform();

these lines must be changed to

PHP code
include_once('./apps/core/pagecontroller/pagecontroller.php'); import('core::frontcontroller','Frontcontroller'); $fC = &Singleton::getInstance('Frontcontroller'); $fC->setContext('sites::demosite'); echo $fC->start('sites::demosite::pres::templates','website');

The context of your application and the path and the name of the initial template must be set as desired in your project.

The adaption described above is only necessary for releases up to 1.13. Since version 1.14 the Front controller is used within the bootstrap file for request processing by default.

After this change is done, the front controller action must be configured. For this reason, the front controller expects the configuration file

Code
/APF/config/modules/captcha/biz/{CONTEXT}/{ENVIRONMENT}_actionconfig.ini
containing the action configuration when calling the image url
Code
/?APF_modules_captcha_biz-action:showCaptcha=name:...
or in case of url rewriting activated, the url
Code
/~/APF_modules_captcha_biz-action/showCaptcha/name/...

(see source code of the taglib). {CONTEXT} and {ENVIRONMENT} must be replaced with the correct values from your project. For details on configuration, please refer to Configuration.

The content of the configuration file is as follows:

APF configuration
[showCaptcha] FC.ActionClass = "APF\modules\captcha\biz\actions\ShowCaptchaImageAction"
The apf-configpack-* release files additionally contain a sample configuration file (EXAMPLE_actionconfig.ini) within the /config/modules/captcha/biz/actions folder.


2. Inclusion of the tag

In order to use the captcha tag, it must be announced within the desired form. This can be achieved using the <form:addtaglib /> tag, whose functionality is nearly the same as the <core:addtaglib />. After that, the tag can be placed within the form. The following code box shows a typical example including the commonly used attributes of the tag:
APF template
<html:form name="MyForm" action="post"> ... <form:addtaglib namespace="modules::captcha::pres::taglib" class="SimpleCaptchaTag" prefix="form" name="captcha" /> <form:captcha text_class="input_field" text_style="width: 318px;" clearonerror="true" /> ... </html:form>
Please note, that with version 1.11, it is necessary to apply a validator to the CAPTCHA field. For this reason, the CaptchaValidator can be used. In case, the CAPTCHA field should be secured, the CaptchaFilter located in modules::captcha::pres::filter can be taken.
Looking at the output of the form, the tag creates a captcha image and a text field, that can be used to fill in the captcha string. The list displayed afterwards describes the attributes of the captcha tag:
  • image_style: CSS styles of the captcha image
  • image_class: CSS classes of the captcha image
  • image_id: HTML ID of the captcha image
  • text_style: CSS styles of the text field
  • text_class: CSS classes of the text field
  • text_id: HTML-ID of the text field
  • validate: Activation of the validation
  • button: Name of the button of the form
  • clearonerror: This optional attribute indicates, that the content of the field is cleared on wrong user input. If the field contains an other value than "true" or is not present, the field is prefilled as usual.
  • clearonformerror: This optional attribute indicates, that the content of the field is be cleared in case the form contains any validation error. If the field contains an other value than "true" or is not present, the field is prefilled as usual.
  • disable_inline: If this optional attribute is set to true the inline CSS styles are disabled. In case the attribute contains another value or is not present, styles are applied, that make the CAPTCHA image and the text field being displayed within one line.

3. Functionality of the tag

By means of directly integrating the captcha tag into a form, the tag can influence the form's valiation. If the captcha string was correctly filled in the text field provided, the form's state is set to "valid". If not, the tag lib implementation marks the form as "invalid" and the user cannot finally submit the form. To ensure, that the form cannot be sent on wrong captcha string input, the form must be checked having the isSent() and isValid() event in the cooresponding controller. For security reasons, the captcha image is regenerated with each request.


Comments

Do you want to add a comment to the article above, or do you want to post additional hints? So please click here. Comments already posted can be found below.
There are no comments belonging to this article.