README

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: sur.max@gmail.com
  Plugin Homepage: http://expressica.com/simple_captcha

  Any feedback/comment/issue/donation is welcome!

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