Introduction

This plugin is designed to make using the ReCaptcha and Mailhide services within Grails easy. In order to use this plugin, you must have a ReCaptcha account, available from http://recaptcha.net.

Installation

This plugin is easily installed from the Grails plugin repository.

Issue this command to install: grails install-plugin recaptcha .

Usage - ReCaptcha

The plugin is simple to use. In order to use it, there are four basic steps:

Edit the Configuration

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

recaptcha {
    // These keys are generated by the ReCaptcha service
     publicKey = ""
     privateKey = ""
   // Include the noscript tags in the generated captcha
     includeNoScript = true
}
mailhide {
    publicKey = ""
    privateKey = ""
}
environments {
  development {
    recaptcha {
      // Set to false to disable the display of captcha
      enabled = false
      // Communicate using HTTPS
      useSecureAPI = false
    }
  }
  production {
    recaptcha {
      // Set to false to disable the display of captcha
      enabled = true
      // Communicate using HTTPS
      useSecureAPI = true
    }
  }
}

Use the Tag Library

The plugin includes four ReCaptcha tags: <recaptcha:ifEnabled> , <recaptcha:ifDisabled>@, @<recaptcha:recaptcha> , and <recaptcha:ifFailed> .

• 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:ifDisabled> tag is a simple utility tag that will render the contents of the tag if the captcha is disabled 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.
• The <recaptcha:ifFailed> tag will render its contents if the previous validation failed. Some ReCaptcha themes, like "clean", do not display error messages and require the developer to show an error message. Use this tag if you're using one of these themes.

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 errors from the session.

Examples

Here's a simple example pulled from an account creation application.

Tag Usage

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

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

If you are using a theme that does not supply error messages, your code might look like this:

<recaptcha:ifEnabled>
    <recaptcha:recaptcha theme="clean"/>
    <recaptcha:ifFailed>CAPTCHA Failed</recaptcha:ifFailed>
</recaptcha:ifEnabled>

Verify User Input

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

import com.megatome.grails.RecaptchaService
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])
        }
    }
}

Sample Using a Custom Theme

<g:form action="validateCustom" method="post" >
    <div id="recaptcha_widget" style="display:none">
        <div id="recaptcha_image" style="width:300px;height:57px;"></div>
        <div class="recaptcha_only_if_incorrect_sol" style="color:red;">
            Incorrect Answer
        </div>
        Enter the words above:
        <input id="recaptcha_response_field" name="recaptcha_response_field" type="text" autocomplete="off"/>
        <div>
            <a href="javascript:Recaptcha.reload()">Get another CAPTCHA</a>
        </div>
        <div class="recaptcha_only_if_image">
            <a href="javascript:Recaptcha.switch_type('audio')">Get an audio CAPTCHA</a>
        </div>
        <div>
            <a href="javascript:Recaptcha.showhelp()">Help</a>
        </div>
   </div>
   <recaptcha:ifEnabled>
       <recaptcha:recaptcha theme="custom" lang="en" custom_theme_widget="recaptcha_widget"/>
   </recaptcha:ifEnabled>
   <br/>
   <g:submitButton name="submit"/>
</g:form>

Testing

With version 0.4.5, the plugin should be easier to integrate into test scenarios. You can look at the test cases in the plugin itself, or you can implement something similar to:

private void buildAndCheckAnswer(def postText, def expectedValid, def expectedErrorMessage) {
    def mocker = new MockFor(Post.class)
    mocker.demand.getQueryString(4..4) { new QueryString() }
    mocker.demand.getText { postText }
    mocker.use {
      def response = recaptchaService.checkAnswer("123.123.123.123", "abcdefghijklmnop", "response")
      assertTrue response.valid == expectedValid
      assertEquals expectedErrorMessage, response.errorMessage
    }
}

The postText parameter represents the response from the ReCaptcha server. Here are examples of simulating success and failure results:

public void testCheckAnswerSuccess() {
    // ReCaptcha server will return true to indicate success
    buildAndCheckAnswer("true", true, null)
}
public void testCheckAnswerFailure() {
    // ReCaptcha server will return false, followed by the error message on a new line for failure
    buildAndCheckAnswer("false\\nError Message", false, "Error Message")
}

Usage - Mailhide

Edit the Configuration

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

… ReCaptcha configuration...
mailhide {
    publicKey = ""
    privateKey = ""
}
...ReCaptcha configuration...

Use the Tag Library

The plugin includes two Mailhide tags: <recaptcha:mailhide> and <recaptcha:mailhideURL> .

• The <recaptcha:mailhide> tag creates a Mailhide URL that opens in a new, pop-up window per the Mailhide specification. It supports one attribute: "emailAddress", to specify the email to be hidden. The link will be created around whatever content is in the body of the tag.
• The <recaptcha:mailhideURL> tag creates a "raw" URL that can be used however desired. This is useful if the pop-up behavior of the other tag is not wanted. It supports two attributes: "emailAddress" and "var". The "emailAddress" attribute specifies the email to be hidden, while the "var" attribute specifies the name of the variable that the created URL should be available under in the page. The URL variable is only available in the context of the tag body.

Examples

mailhide tag

<recaptcha:mailhide emailAddress="x@example.com">Some text to wrap in a link</recaptcha:mailhide>

will create:

<a href="http://www.google.com/recaptcha/mailhide/d?k=...publicKey...&c=..encryptedEmail..."
     onclick="window.open('http://www.google.com/recaptcha/mailhide/d?k=...publicKey...&c=...encryptedEmail...', '', 
     'toolbar=0,scrollbars=0,location=0,statusbar=0,menubar=0,resizable=0,width=500,height=300'); return false;" 
     title="Reveal this e-mail address">Some text to wrap in a link</a>

mailhideURL tag

<recaptcha:mailhideURL emailAddress="x@example.com" var="mu">
Created Mailhide URL: ${mu}
</recaptcha:mailhideURL>

will create:

Created Mailhide URL: http://www.google.com/recaptcha/mailhide/d?k=...publicKey...&c=...encryptedEmail...

Misc.

CHANGELOG

• 0.5.0 Add Mailhide support. Add support for specifying configuration options elsewhere than RecaptchaConfig.groovy via the grails.config.locations method.
• 0.4.5 Add code to perform the ReCaptcha functionality - removed recaptcha4j library. Don't add captcha instance to session to avoid serialization issues. Hopefully make it easier to test against.
• 0.4 New version number for Grails 1.1. Same functionality as 0.3.2
• 0.3.2 Moved code into packages. Tried to make licensing easier to discern. Updated to Grails 1.0.4
• 0.3 Added support for environments and new <recaptcha:ifFailed> tag. Updated to Grails 1.0.3
• 0.2 initial release, developed and tested against Grails 1.0.2

KNOWN ISSUES

• If you are testing locally on a Mac, you may need to change recaptchaService.verifyAnswer(session, request.getRemoteAddr(), params) to recaptchaService.verifyAnswer(session, "127.0.0.1", params) . This seems to be an issue with the ReCaptcha service not being able to handle the IPV6 localhost identifier.

TODO

• Automate session cleanup

Suggestions or Comments

Feel free to submit questions or comments to the Grails users mailing list.

http://grails.org/Mailing+lists

Alternatively you can contact me directly - cjohnston at megatome dot com