Copyright (c) 2008 [Sur http://expressica.com]

SimpleCaptcha3

Version: edge(Only for Rails 3.*) Author: Sur [http://expressica.com] Plugin URL: http://github.com/bansalakhil/SimpleCaptcha3 Contributors: http://vinsol.com/team, Kei Kusakari [http://d.hatena.ne.jp/kusakari/about] License: MIT

Introduction:

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

SimpleCaptcha(older version of SimpleCaptcha3) is also available to be used with Rails2.0 or above and also it provides the backward compatibility with previous versions of Rails. (http://expressica.com/simple_captcha)

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_simple_captcha %>" within the 'form' tags. -> Flexible DOM and CSS handling(There is a separate view partial for rednering SimpleCaptcha3 DOM elements). -> Automated removal of 1 hour old unmatched simple_captcha data.

Pre-Requisite

RMagick should be installed on your machine to use this plugin. visit http://rmagick.rubyforge.org for more details.

Installation

SimpleCaptcha3 plugin can be installed by running this command from the application root

rails plugin install git://github.com/bansalakhil/SimpleCaptcha3.git

Setup

After installation, follow these simple steps to setup the plugin.

STEP 1

>> rake simple_captcha:setup

STEP 2

>> rake db:migrate

STEP 3

add the following code in the file config/routes.rb

match '/simple_captcha(/:action)' => 'simple_captcha', :as => :simple_captcha

This is a mandatory route used for rendering the simple_captcha image on the fly without 
storing on the filesyste.

STEP 4

add the following line in the file app/controllers/application.rb

ApplicationController < ActionController::Base
  include SimpleCaptcha::ControllerHelpers
end

Usage

Controller Based

In the view file within the form tags add this code

<%= show_simple_captcha %>

and in the controller's action authenticate it as 

  if simple_captcha_valid?
    do this
  else
    do that
  end

Model Based

In the view file within the form tags write this code

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

and in the model class add this code

class User < ActiveRecord::Basse
  apply_simple_captcha
end

Validating with captcha
---------------------------------------------------------------------------------------
  @user.valid_with_captcha?
  NOTE: @user.valid? will still work as it should, it will not validate the captcha code.

Saving with captcha
---------------------------------------------------------------------------------------
  @user.save_with_captcha
  NOTE: @user.save will still work as it should, it will not validate the captcha code.

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
  
  Default style is 'simply_blue'.
  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 SimpleCaptcha DOM elements ?
-----------------------------------------------------
You can change the CSS of the SimpleCaptcha DOM elements as per your need in this file.
For Rails >= 2.0 the file wiil reside as...
"/app/views/simple_captcha/_simple_captcha.erb"
For Rails < 2.0 the file will reside as...
"/app/views/simple_captcha/_simple_captcha.rhtml"

View's Examples

Controller Based Example
---------------------------------------------------------------------------------------
  example
  -------
  <%= show_simple_captcha(:label => "human authentication") %>
  
  example
  -------
  <%= show_simple_captcha(:label => "human authentication", :image_style => 'embosed_silver') %>

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

Model Based Example
---------------------------------------------------------------------------------------
  
  example
  -------
  <%= show_simple_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_simple_captcha
  end

  example
  -------
  class User < ActiveRecord::Base
    apply_simple_captcha :message => "The secret Image and code were different", :add_to_base => true
  end

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

Enjoy the simplest captcha implementation. Author: Sur Blog: http://expressica.com Contact: [email protected] Plugin Homepage: http://expressica.com/simple_captcha

Any feedback/comment/issue/donation is welcome!

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