README

SimpleCaptcha

Fork of http://github.com/eshopworks/simple_captcha/tree by Marek de Heus

Website: http://expressica.com/simple_captcha/
Svn: svn://rubyforge.org/var/svn/expressica/plugins/simple_captcha

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

Author: Sur
Contributors: http://vinsol.com/team, Kei Kusakari, nap

  Introduction:
  -------------
  This forked version is different in a few ways. I changed it so that the
  captcha validation is just that: another validation. This makes it much
  easier to use it in combination with things like resource_controller.
  
  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.
  
  I have written some tests (the original didn't have any) as part of another
  project. If I have the time I will include them here.
  
  - Marek

  
  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::Base
      validates_captcha :on => :create
    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
      
      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
        validates_captcha
      end

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

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

  Enjoy the simplest captcha implementation.
  Author: Sur
  Blog: http://expressica.com
  Contact: sur.max@gmail.com
  Plugin Homepage: http://expressica.com/simple_captcha

  Any feedback/comment/issue/donation is welcome!

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