Recaptcha Element

Home | Getting Started | API | Elements | Actions | Validators | Handlers | Configuration Options | Plugins | Mobile | Troubleshooting | About

Table of Contents

1 Recaptcha Element - #recaptcha{}

Overview

The recaptcha element produces a recaptcha element. For more information about recaptchas you may refer to https://developers.google.com/recaptcha/

The element is rendered and evaluated by an external library.

The captcha is processed as follows:

  • The user solves the captcha.
  • If the solution is wrong the captcha gets refreshed until the user gives up or the solution is correct, and a Page:recaptcha_event is called with a Result of error.
  • If the solution is correct the Page:recaptchaevent callback is called with a Result of ok.
  • The return value of the Page:recaptcha_event callback is evaluated as follows:
    • If the value is ok nothing is done.
    • If the return value is error, the captcha gets refreshed.
    • If the return value is {error, Msg}, the captcha gets refreshed and the Msg is shown as the error message.

Preparations

Before you can use the the recaptcha element, you have to register at https://www.google.com/recaptcha/admin/create.

After that, you have to either specify the following values in your app.config or specify them as attributes to the #recaptcha{} element itself.

[
 {nitrogen, [
             {recaptcha, 
              [{public_key, "recaptcha_public_key"},
               {private_key, "recaptcha_private_key"},
               {challenge_url, "http://www.google.com/recaptcha/api/challenge"},
               {verify_url, "http://www.google.com/recaptcha/api/verify"}]}
               ...
 ]},
 ...
].

Usage

#recaptcha {
   public_key="some_public_key",
   private_key="some_private_key"
}

Attributes

The following attributes are required unless they are defined as nitrogen environment variables above.

public_key - (string)
Public key provided by the Recaptcha service.
private_key - (string)
Private key provided by the Recaptcha service.

The following attributes are optional

tag - (term)
The "tag" for the recaptcha element to be passed to the recaptcha_event/2 function
button_id - (atom)
The button's id
button_label - (string)
The button's label
captcha_opts - (proplist)
The captcha's options. For more information see the official Recaptcha Documentation custom_theme_widget is not supported
delegate (Module)
The module where the event callback gets called
fail_body (List)
The fail message. It can be a simple string or an array of Nitrogen elements. It will be displayed below the recaptcha if the user fails to enter the correct recaptcha.
challenge_url - (string)
The challenge URL as specified in the Recaptcha Documentation (default: https://www.google.com/recaptcha/api/challenge")
verify_url - (string)
The verification URL as specified in the Recaptcha Documentation (default: https://www.google.com/recaptcha/api/verify")

Postback Function

When a recaptcha succeeds or fails, the recaptcha_event/2 function is called on your page module. Tag will be from the tag attribute above, and Result will be a status atom, either ok if successful, or {error, ErrorMessage} if the recaptcha fails.

recaptcha_event/2 can return any of the following:

  • ok - Everything is okay.
  • error - There was something that failed (maybe you did some data validation in the event_recaptcha/2 function and something failed so let's just return an error.
  • {error, ErrorMessage} - Something went wrong, and let's set the error message to the contents of ErrorMessage (which, like fail_body above, can be either text or Nitrogen elements).
recaptcha_event(_Tag, ok) ->
   wf:wire(#alert{text="Congrats, you're human"}),
   ok;
recaptcha_event(_Tag, {error, ErrorReason}) ->
   wf:wire(#alert{text="WE THINK YOU'RE A ROBOT! YOU MUST PROVE OTHERWISE!"}),
   {error, "Please Try again!"}.

Regarding Validation with Recaptcha

If you wish to trigger validators before the Recaptcha gets used, you'll need to wire the validators to the Recaptcha's button_id attribute.

You can see this in use in the example below:

Example

Code in a page module may look like this:

inner_body() ->
   %% Wire a validator to be triggered by `recaptcha_button`, and target `name`
   wf:wire(recaptcha_button, name, #validate{ validators=[
      #is_required{}
   ]}),
   [
      #label{text="Enter your name"},
      #textbox{id=name},
      #recaptcha{
         button_id=recaptcha_button,
         id=recaptcha,
         tag=my_recaptcha,
         captcha_opts=[{theme,white}]
      }
   ].

event_recaptcha(my_recaptcha, ok) ->
    case check_user_input() of
        ok     -> wf:remove(recaptcha),
                  ok;
        error  -> {error, "FAIL!"}
    end.

check_user_input() ->
%% your check routine

Date: 2013-10-20 21:59:23 CDT

Author: Steffen Panning

Org version 7.8.02 with Emacs version 23

Validate XHTML 1.0

Comments

Note:To specify code blocks, just use the generic code block syntax:
<pre><code>your code here</code></pre>


comments powered by Disqus