Integrating Image CAPTCHA In Form Templates
Image CAPTCHA is implemented into forms by adding the CAPTCHA input tag and image tags to your form template. These fields only work once CAPTCHA has been enabled. View the documentation for more information on enabling image CAPTCHA and its configuration options.
To properly implement CAPTCHA into a form, three parts are required:
- The CAPTCHA image.
- The CAPTCHA input field.
- A reload link for the user to request a new image.
Setting up the CAPTCHA Image
In this example the CAPTCHA image is given an ID in the configuration settings. The ID is used to select the image in the Javascript code example below. The ID for the image isn't necessary as you can select the image in a different way. This is just how we're doing it for this example.
Form Template HTML
Below is an example of a form template using the CAPTCHA image and input field. You can, of course, use different HTML.
<div class="form-container">
{loop items="#form.fields" value="field"}
<div class="field-wrap">
<label for="{#field.id}">
{#field.label}
</label>
{#field.tag}
</div>
{/loop}
<div class="captcha-image">
{#form.captcha.image.tag}
</div>
<div class="field-wrap">
{#form.captcha.tag}
<span>Can't read it?
<a href="{#form.captcha.reloadUrl}" id="captchaReload" rel="nofollow">
Request a new code
</a>
</span>
</div>
</div>
The {#form.captcha.tag} variable will output the text field where the user can input the CAPTCHA value and a hidden form field that is used by the system to validate the CAPTCHA value. The HTML for the hidden field is something like this:
<input type="hidden" value="239d93c0af8aa03282e664ffefef930c" name="ap-form-captcha[id]">
The value of the hidden field is a special key used to validate the CAPTCHA value. When the CAPTCHA image is refreshed with Javascript the value of this hidden field also needs to be updated.
Form Template Javascript
Javascript is required for the user to be able to reload the image and stay on the same page. An example of the script can be seen here. We are using jQuery in this example. You can use any library that you want or use raw Javascript.
$(document).ready(function(){
$('#captchaReload').click(function() {
$.getJSON(this.href, function(data) {
try{
$('input[name="ap-form-captcha[id]"]').val(data.captchaId);
$('#captcha-img').attr('src', data.src);
} catch(e) {
alert('There was a problem refreshing the captcha image. ' + e);
}
});
return false;
});
});
The above Javascript is essentially handling the click event on the reload link and using the JSON response to update the CAPTCHA image and the hidden field value.
Be sure that your Javascript is updating the correct CAPTCHA image. You can assign a class or ID to your CAPTCHA elements in the CAPTCHA settings tab in the edit form window. View the documentation for more information on CAPTCHA configuration options.
JSON Response for Reloading the CAPTCHA Image
The server response from getting a new CAPTCHA image will always be a JSON response. Below is an example response. As you can see there is more information being returned then what the sample Javascript above is using. This gives you the flexibility to handle the response the way that you want to.
{
"status":"ok",
"src":"\/images\/captcha\/811a4f8eb55b41ba59ae356f3ad33b42.png",
"captchaId":"811a4f8eb55b41ba59ae356f3ad33b42",
"height":50,
"width":200,
"image":"<img width=\"200\" height=\"50\" alt=\"\" src=\"\/images\/captcha\/811a4f8eb55b41ba59ae356f3ad33b42.png\" id=\"captcha-img\" style=\"\" \/>",
"tag":"<input type=\"hidden\" name=\"ap-form-captcha[id]\" value=\"811a4f8eb55b41ba59ae356f3ad33b42\" \/><input type=\"text\" name=\"ap-form-captcha[input]\" id=\"captcha-field\" value=\"\" \/>"
}
Below is a description of each part of the JSON response.
status - Whether or not the request to get a new CAPTCHA image was successful. The value will be "ok" or "error". "ok" means it was successful. "error" means there was an error and if that's the case then an additional "message" value will be returned.
src - The new CAPTCHA image tag path.
captchaId - The new value for the hidden field. If you don't update the hidden field value then the CAPTCHA will not validate correctly.
height - The height of the new CAPTCHA image.
width - The width of the new CAPTCHA image.
image - The full tag for the new CAPTCHA image.
tag - The full tag for the hidden field and text field.