= reCAPTCHA

Author::    Jason L Perry (http://ambethia.com)
Copyright:: Copyright (c) 2007-2013 Jason L Perry
License::   {MIT}[http://creativecommons.org/licenses/MIT/]
Info::      http://github.com/ambethia/recaptcha
Bugs::      http://github.com/ambethia/recaptcha/issues

This plugin adds helpers for the {reCAPTCHA API}[https://www.google.com/recaptcha]. In your
views you can use the +recaptcha_tags+ method to embed the needed javascript,
and you can validate in your controllers with +verify_recaptcha+ or +verify_recaptcha!+,
which throws an error on failiure.

Beforehand you need to configure Recaptcha with your custom private and public
key. You may find detailed examples below. Exceptions will be raised if you
call these methods and the keys can't be found.

== Rails Installation

reCAPTCHA for Rails > 3.0, add this to your Gemfile:

  gem "recaptcha", :require => "recaptcha/rails"

Rails apps below 3.0 are no longer supported, but you can install an older
release and view it's README.

== Setting up your API Keys

There are multiple ways to setup your reCAPTCHA API key once you
{obtain}[https://www.google.com/recaptcha/admin] a pair.

=== Recaptcha.configure

You may use the block style configuration. The following code could be placed
into a +config/initializers/recaptcha.rb+ when used in a Rails project.

  Recaptcha.configure do |config|
    config.public_key  = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
    config.private_key = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
    # Uncomment the following line if you are using a proxy server:
    # config.proxy = 'http://myproxy.com.au:8080'
    # Uncomment if you want to use the newer version of the API,
    # only works for versions >= 0.3.7:
    # config.api_version = 'v2'
  end

This way, you may also set additional options to fit recaptcha into your
deployment environment.

== Recaptcha#with_configuration

If you want to temporarily overwrite the configuration you set with `Recaptcha.configure` (when testing, for example), you can use a `Recaptcha#with_configuration` block:

  Recaptcha.with_configuration(:public_key => '12345') do
    # Do stuff with the overwritten public_key.
  end

=== Heroku & Shell environment

Or, you can keep your keys out of your code base by exporting the following
environment variables. You might do this in the .profile/rc, or equivalent for
the user running your application. This would also be the preffered method
in an Heroku deployment.

  export RECAPTCHA_PUBLIC_KEY  = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
  export RECAPTCHA_PRIVATE_KEY = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'

=== Per call

You can also pass in your keys as options at runtime, for example:

  recaptcha_tags :public_key => '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'

and later,

  verify_recaptcha :private_key => '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'

This option might be useful, if the same code base is used for multiple
reCAPTCHA setups.

== To use 'recaptcha'

Add +recaptcha_tags+ to each form you want to protect. Place it where you want the recaptcha widget to appear.

Example:

  <%= form_for @foo do |f| %>
    # ... additional lines truncated for brevity ...
    <%= recaptcha_tags %>
    # ... additional lines truncated for brevity ...
  <% end %>

And, add +verify_recaptcha+ logic to each form action that you've protected.

=== +recaptcha_tags+

Some of the options available:

<tt>:ssl</tt>::         Uses secure http for captcha widget (default +false+, but can be changed by setting +config.use_ssl_by_default+)
<tt>:noscript</tt>::    Include <noscript> content (default +true+)
<tt>:display</tt>::     Takes a hash containing the +theme+ and +tabindex+ options per the API. (default +nil+), options: 'red', 'white', 'blackglass', 'clean', 'custom'
<tt>:ajax</tt>::        Render the dynamic AJAX captcha per the API. (default +false+)
<tt>:public_key</tt>::  Your public API key, takes precedence over the ENV variable (default +nil+)
<tt>:error</tt>::       Override the error code returned from the reCAPTCHA API (default +nil+)

You can also override the html attributes for the sizes of the generated +textarea+ and +iframe+
elements, if CSS isn't your thing. Inspect the source of +recaptcha_tags+ to see these options.

=== +verify_recaptcha+

This method returns +true+ or +false+ after processing the parameters from the reCAPTCHA widget. Why
isn't this a model validation? Because that violates MVC. You can use it like this, or how ever you
like. Passing in the ActiveRecord object is optional, if you do--and the captcha fails to verify--an
error will be added to the object for you to use.

Some of the options available:

<tt>:model</tt>::       Model to set errors
<tt>:attribute</tt>::   Model attribute to receive errors (default :base)
<tt>:message</tt>::     Custom error message
<tt>:private_key</tt>:: Your private API key, takes precedence over the ENV variable (default +nil+).
<tt>:timeout</tt>::     The number of seconds to wait for reCAPTCHA servers before give up. (default +3+)

  respond_to do |format|
    if verify_recaptcha(:model => @post, :message => "Oh! It's error with reCAPTCHA!") && @post.save
      # ...
    else
      # ...
    end
  end

== I18n support
reCAPTCHA passes two types of error explanation to a linked model. It will use the I18n gem
to translate the default error message if I18n is available. To customize the messages to your locale,
add these keys to your I18n backend:

<tt>recaptcha.errors.verification_failed</tt>:: error message displayed if the captcha words didn't match
<tt>recaptcha.errors.recaptcha_unreachable</tt>:: displayed if a timeout error occured while attempting to verify the captcha

Also you can translate API response errors to human friendly by adding translations to the locale (+config/locales/en.yml+):

  en:
    recaptcha:
      errors:
        incorrect-captcha-sol: 'Fail'

== TODO
* Remove Rails/ActionController dependencies
* Framework agnostic
* Add some helpers to use in before_filter and what not
* Better documentation