Edit the Configuration

The plugin creates a file called RecaptchaConfig.groovy in grails-app/conf that has the following content:

recaptcha {
	// Set to false to disable the display of captcha
	enabled = true

	// These keys are generated by the ReCaptcha service
	publicKey = ""
	privateKey = ""

	// Include the noscript tags in the generated captcha
	includeNoScript = true

	// Communicate using HTTPS
	useSecureAPI = false
}

The values are pretty self-explanatory, and match with values used by the ReCaptcha service. You must enter your public and private ReCaptcha keys, or errors will be thrown when trying to display a captcha.

Use the Tag Library

The plugin includes two tags: <recaptcha:ifEnabled> and <recaptcha:recaptcha>.

• The <recaptcha:ifEnabled> tag is a simple utility tag that will render the contents of the tag if the captcha is enabled in RecaptchaConfig.groovy.
• The <recaptcha:recaptcha> tag is responsible for generating the correct HTML output to display the captcha. It supports four attributes: "theme", "lang", "tabindex", and "custom_theme_widget". These attributes map directly to the values that can be set according to the ReCaptcha API. See the ReCaptcha Client Guide for more details.

Verify the Captcha

In your controller, call recaptchaService.verifyAnswer(session, request.getRemoteAddr(), params) to verify the answer provided by the user. This method will return true or false, but will set the error_message property on the captcha behind the scenes so that the error message will be properly displayed when the ReCaptcha is redisplayed. Also note that verifyAnswer will return true if the plugin has been disabled in the configuration - this means you won't have to change your controller.

Clean up After Yourself

Once the captcha has been verified, call recaptchaService.cleanup(session). This is not strictly needed, but it will clean the captcha instance and any associated errors from the session. I'm sure there's a better way to do this - can somebody give me a pointer?

Tag Usage

In create.gsp, we add the code to show the captcha:

<recaptcha:ifEnabled>
    <recaptcha:recaptcha theme="blackglass"/>
</recaptcha:ifEnabled>

In this example, we're using ReCaptcha's "blackglass" theme. Leaving out the "theme" attribute will default the captcha to the "red" theme.

Verify User Input

Here's an abbreviated controller class that verifies the captcha value when a new user is saved:

class UserController {
    RecaptchaService recaptchaService

    def save = {
        def user = new User(params)
        ...other validation...
        def recaptchaOK = true
        if (!recaptchaService.verifyAnswer(session, request.getRemoteAddr(), params)) {
        	recaptchaOK = false
        }
        if(!user.hasErrors() && recaptchaOK && user.save()) {
            recaptchaService.cleanUp(session)
            ...other account creation acivities...
            render(view:'showConfirmation',model:[user:user])
        }
        else {
            render(view:'create',model:[user:user])
        }
    }
}

CHANGELOG

• 0.2 initial release, developed and tested against Grails 1.0.2

TODO

• Automate session cleanup