displayCaptcha()

Please note: this method and its configuration have changed from Form Tools 2.

Overview

The displayCaptcha() method is for adding a CAPTCHA to your API forms, to help combat spam.

The API comes fully integrated with the reCAPTCHA service, offered by Google. Click here to visit their website and learn more.

This API method generates a CAPTCHA in your page with a single line of PHP. Unlike earlier CAPTCHAs, the new version

This document explains how to get this function working for you.

1. Set up reCAPTCHA for your website

• Visit the reCAPTCHA site here and sign up for an API key pair.
• Once you've created an account you register the domain(s) where you're using the service. Since the API only runs on the same server as your Form Tools installation, you'll only need to set up the one domain. You will need to choose the reCAPTCHA V2 option.
• Tip: if you're developing locally, you can enter both localhost and 127.0.0.1 in the Domains section.

Once it's set up, reCAPTCHA will generate two keys for you: a site key and a secret key. Add those two values to your Form Tools global/config.php file, like so:

(replace the x's and y's with your own keys).

2. Add the reCAPTCHA to your form

In your form (which should already be integrated with the API with help from the tutorials on adding a single page form and adding a multi-page form), add this line wherever you want.

At this point, if you refresh your web browser you should see the captcha appear in the page. So far so good! Next, we want to explicitly tell the API that this page contains a CAPTCHA so no-one can circumvent the test by modifying the POST request. Add a new "has_captcha" => true key-value pair to your processFormSubmission() method call, like so:

Great! Now your CAPTCHA is working on your form. Try submitting your form without checking the "I'm not a robot" field. You should get redirected back to the same page and not continue.

Validation errors

Unlike earlier CAPTCHAs where user mistakes were common, the new ones are just a checkbox - not much room for error! Nevertheless, if you'd like to catch for errors here's how to do it.

The default behaviour for the displayCaptcha() method is to display a simple "There was a reCAPTCHA error." message in English in a div with a .form_tools_recaptcha_error class in the page above the CAPTCHA. If you'd like to fine-fune this, just pass in a single false property to the displayCaptcha() method and that will suppress the error.

To add your own error message in the page (wherever you want it) just check for the $GLOBALS["g_api_recaptcha_error"] property. That will be set after an error and contain the error response from the Google recaptcha validation method.