ruby-recaptcha

= ruby-recaptcha

• http://www.bitbucket.org/mml/ruby-recaptcha

== Installing

  gem install recaptcha

== The basics

The ReCaptchaClient abstracts the ReCaptcha API for use in Rails Applications

== Demonstration of usage

=== reCAPTCHA

First, create an account at "ReCaptcha.net":http://www.recaptcha.net.

Get your keys, and make them available as constants in your application. You can do this however you want, but RCC_PUB, RCC_PRIV (for regular reCaptcha) and MH_PUB MH_PRIV (for MailHide) must be set to their respective values (the keys you receive from reCaptcha).

The two common methods of doing this (for Rails applications) are to set these variables in your environment.rb file, or via an environment variable, or in Rails 2.2+, in an initializer.

The ReCaptcha::Client constructor can also take an options hash containing keys thusly:

  Recaptcha::Client.new(:rcc_pub=>'some key', :rcc_priv=>'some other key')

In recent versions of Rails, you can specify the gem in environment.rb:

  config.gem 'ruby-recaptcha'

After your keys are configured, and the gem is loaded, include the ReCaptcha::AppHelper module in your ApplicationController:

class ApplicationController < ActionController::Base
  include ReCaptcha::AppHelper

This will mix-in validate_recap method.

Then, in the controller where you want to do the validation, chain validate_recap() into your regular validation:

  def create
      @user = User.new(params[:user])
      if validate_recap(params, @user.errors) && @user.save
             ...do stuff...

Require and include the view helper in your application_helper: NOTE: require is used here, not gem, not sure why.

  include ReCaptcha::ViewHelper

This will mix get_captcha() into your view helper.

Now you can just call

get_captcha()

in your view to insert the requisite widget from ReCaptcha.

To customize theme and tabindex of the widget, you can include an options hash:

get_captcha(:options => {:theme => 'white', :tabindex => 10})

See the "reCAPTCHA API Documentation": under "Look and Feel Customization" for more information.

=== Proxy support

If your rails application requires the use of a proxy, set proxy_host into your environment:

  ENV['proxy_host']='foo.example.com:8080'

=== Mail Hide

When you mix in ViewHelper as above, you also get

 mail_hide(address, contents)

, which you can call in your view thusly:

  ...
  <%= mail_hide(user.email) %>

Contents defaults to the first few characters of the email address.

== Bugs

http://www.bitbucket.org/mml/ruby-recaptcha/issues

== Code

Get it "here":http://www.bitbucket.org/mml/ruby-recaptcha

Note the wiki & forum & such there...

== License

This code is free to use under the terms of the MIT License.

== Contact

Comments are welcome. Send an email to "McClain Looney":mailto:[e-mail].

== Contributors:

Victor Cosby (test cleanup, additional code to style widget)
Ronald Schroeter (proxy support suggestion & proto-patch)
Peter Vandenberk (multi-key support, ssl support, various unit tests, test refactoring)
Kim Griggs (found long address-newline bug)