Skip to content

Latest commit

 

History

History
150 lines (101 loc) · 5.58 KB

README.rdoc

File metadata and controls

150 lines (101 loc) · 5.58 KB
Raw

reCAPTCHA ↑

Author

Jason L Perry (ambethia.com)

Copyright

Copyright © 2007 Jason L Perry

License

MIT

Info

ambethia.com/recaptcha

Git

github.com/ambethia/recaptcha/tree/master

Bugs

github.com/ambethia/recaptcha/issues

This plugin adds helpers for the reCAPTCHA API. 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.

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.

About this fork ↑

This fork tries to introduces a more convenient way to configure recaptcha’s settings. The API will be inspired by Thoughtbot’s Hoptoad.

Rails Installation ↑

reCAPTCHA for Rails, add this to your Gemfile:

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

Or, it can be installed as a gem:

config.gem "recaptcha", :lib => "recaptcha/rails"

Or, as a standard rails plugin:

script/plugin install git://github.com/ambethia/recaptcha.git

Merb Installation ↑

reCAPTCHA can also be used in a Merb application when installed as a gem:

dependency "alm-recaptcha", ">=0.2.2.1", :require_as => "recaptcha/merb"

Initial Merb compatability funded by ALM Labs.

Setting up your API Keys ↑

There are multiple ways to setup your reCAPTCHA API key once you obtain 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'
  config.proxy = 'http://myrpoxy.com.au:8080'
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.configure(:public_key => '12345') do
  # Do stuff with the overwritten public_key.
end

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:

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.

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

recaptcha_tags ↑

Some of the options available:

:ssl

Uses secure http for captcha widget (default false)

:noscript

Include <noscript> content (default true)

:display

Takes a hash containing the theme and tabindex options per the API. (default nil)

:ajax

Render the dynamic AJAX captcha per the API. (default false)

:public_key

Your public API key, takes precedence over the ENV variable (default nil)

:error

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:

:model

Model to set errors

:attribute

Model attribute to receive errors (default :base)

:message

Custom error message

:private_key

Your private API key, takes precedence over the ENV variable (default nil).

:timeout

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:

recaptcha.errors.verification_failed

error message displayed if the captcha words didn’t match

recaptcha.errors.recaptcha_unavailable

displayed if a timout error occured while attempting to verify the captcha

TODO ↑

  • Remove Rails/ActionController dependencies

  • Framework agnostic

  • Add some helpers to use in before_filter and what not

  • Better documentation