quick_captcha

This code is a fork http://github.com/kares/simple_captcha

Main Updates

• Renamed (mostly) to QuickMagick
• Upgraded to engine running under Rails 3.2
• Removed support for RMagick
• Removed support for Rails 2
• Attempted to maintain backwards compatibility

Other Updates

The original version does all kinds of method aliasing and requires you to write code specifically for handling the captcha validation. This version accepts the usual :if, :unless and :on options.

This version does not bypass the validation if in test mode. It behaves the same in all environments, allowing you to actually test it.

To disable the validations in test mode, You should now state it explicitly:

class User < ActiveRecord::Base
  validates_captcha :unless => lambda { Rails.env.test? }
end

NOTE: This will validate captcha every-time You do a user.save !

There's an API that allows You to (temporary) disable captcha validation for classes, individual instances or even blocks :

User.captcha_validation = false # disables validation globally
user = User.new
...
# force captcha validation for the given instance and block
user.captcha_validation(true) do
  user.save!
end
...
# enable captcha validation for the given instance
user.captcha_validation(true)
user.save
...
# reset captcha validation - fallback to the class setting
user.captcha_validation(nil)
user.save # validates captcha if User.captcha_validation?

Old Validation

A backward compatible validation for Your model classes is as well available. The original captcha validation code was different from standard validation in a way that it did not validate the captcha on "regular" save calls, one has to explicitly state captcha validation is desired by calling save_with_captcha.

class User < ActiveRecord::Base
  apply_simple_captcha :message => 'WTF?!'
end

NOTE: The "old" behavior is emulated using the captcha_validation flags.

QuickCaptcha

QuickCaptcha is the simplest and a robust captcha plugin. Its implementation requires adding up a single line in views and in controllers/models.

Features

• Zero FileSystem usage(secret code moved to db-store and image storage removed).
• Provides various image styles.
• Provides three level of complexity of images.
• Works absolutely fine in distributed environment(session and db based implementation works fine in distributed environment).
• Implementation is as easy as just writing a single line in your view. <%= show_quick_captcha %> within the 'form' tags.
• Flexible DOM and CSS handling(There is a separate view partial for rendering QuickCaptcha DOM elements).
• Automated removal of 1 hour old unmatched simple_captcha data.

Pre-Requisite

quick_magick should be installed on your machine to use this plugin.

Installation

gem install quick_captcha add gem 'quick_captcha' to Gemfile

Setup

After installation, follow these simple steps to setup the plugin. The setup will depend on the version of rails your application is using.

STEP 1

for Rails 3.x :

rails generate quick_captcha

STEP 2

rake db:migrate

STEP 4 (Optional)

configure quick_captcha e.g. in app/config/initializers/quick_captcha.rb

QuickCaptcha.backend = :quick_magick 

QuickCaptcha.image_options = {
    :image_color => 'white',
    :image_size => '110x30',
    :text_color => 'black',
    :text_font => 'arial',
    :text_size => 22
} # these are the defaults

Please note that some image options such as color might change when using some of the pre-built captcha image styles available.

Usage

Controller Based

Include QuickCaptcha::ControllerValidation into Your captcha validating controller or put the include into app/controllers/application.rb

ApplicationController < ActionController::Base
  include QuickCaptcha::ControllerValidation
end

in the view file within the form tags add this code

<%= show_quick_captcha %> or <%= show_simple_captcha %>

and in the controller's action authenticate it as

if quick_captcha_valid?
  do this
else
  do that
end

Model Based

In the view file within the form tags write this code

<%= show_quick_captcha(:object=>"user") %>

and in the model class include QuickCaptcha::ModelValidation and setup the validation

class User < ActiveRecord::Base
  include QuickCaptcha::ModelValidation

  validates_captcha :on => :create, :message => 'invalid captcha'
end

or if You prefer the old version which doesn't trigger the captcha validation on save (one have to call save_with_captcha)

class User < ActiveRecord::Base
  include QuickCaptcha::ModelValidation
  
  apply_quick_captcha :message => :'invalid_captcha'
end

Options & Examples

View Options
==========================================================================

:label
--------------------------------------------------------------------------
  provides the custom text b/w the image and the text field,
  the default is "type the code from the image"

:image_style
--------------------------------------------------------------------------
  Provides the specific image style for the captcha image.
  There are eight different styles available with the plugin as...
  1) simply_blue
  2) simply_red
  3) simply_green
  4) charcoal_grey
  5) embosed_silver
  6) all_black
  7) distorted_black
  8) almost_invisible

  See the included samples <http://github.com/kares/simple_captcha/samples>.
  You can also specify 'random' to select the random image style.


:distortion
--------------------------------------------------------------------------
  Handles the complexity of the image. The :distortion can be set to 'low',
  'medium' or 'high'. Default is 'low'.

:object
--------------------------------------------------------------------------
  the name of the object of the model class, to implement the model based
  captcha.


How to change the CSS for QuickCaptcha DOM elements ?
-----------------------------------------------------
You can change the CSS of the QuickCaptcha DOM elements as per your need
in this file.
"/app/views/quick_captcha/_quick_captcha.erb"


View's Examples
==========================================================================

Controller Based Example
--------------------------------------------------------------------------
  example
  -------
  <%= show_quick_captcha(:label => "human authentication") %>

  example
  -------
  <%= show_quick_captcha(:label       => "human authentication",
                          :image_style => 'embosed_silver') %>

  example
  -------
  <%= show_quick_captcha(:label       => "human authentication",
                          :image_style => 'simply_red',
                          :distortion  => 'medium') %>

Model Based Example
--------------------------------------------------------------------------

  example
  -------
  <%= show_quick_captcha(:object => 'user',
                          :label  => "human authentication") %>



Model Options
==========================================================================

:message
--------------------------------------------------------------------------
  provides the custom message on failure of captcha authentication
  the default is "Secret Code did not match with the Image"

:add_to_base
--------------------------------------------------------------------------
  if set to true, appends the error message to the base.

Model's Example
==========================================================================

  example
  -------
  class User < ActiveRecord::Base
    apply_quick_captcha # the "old" way using save_with_captcha
  end

  example
  -------
  class User < ActiveRecord::Base
    validates_captcha :message => "Are you a bot?", :add_to_base => true
  end

==========================================================================