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

SimpleCaptcha

Version: edge Author: Sur [http://expressica.com] Plugin Homepage: http://expressica.com/simple_captcha Contributors: http://vinsol.com/team, Kei Kusakari [http://d.hatena.ne.jp/kusakari/about] License: MIT

Introduction:

SimpleCaptcha is the simplest and a robust captcha plugin. Its implementation requires adding up a single line in views and in controllers/models. SimpleCaptcha is available to be used with Rails2.0 or above and also it provides the backward compatibility with previous versions of Rails.

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 SimpleCaptcha 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

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

ruby script/plugin install svn://rubyforge.org/var/svn/expressica/plugins/simple_captcha

OR

SVN checkout the plugin as svn co svn://rubyforge.org/var/svn/expressica/plugins/simple_captcha simple_captcha Now put the directory simple_captcha in your application as /vendor/plugins/simple_captcha

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 >= 2.0
---------------
>> rake simple_captcha:setup

for rails < 2.0
---------------
>> rake simple_captcha:setup_old

STEP 2

>> rake db:migrate

STEP 3

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

  ActionController::Routing::Routes.draw do |map|
    map.simple_captcha '/simple_captcha/:action', :controller => 'simple_captcha'
  end

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!

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