=SimpleCaptcha

This is a fork of wolcanus's fork of SimpleCaptcha to support Mongoid 3 and new formtastic.

This is a fork of galetahub SimpleCaptcha to support Mongoid.
Its implementation requires
adding up a single line in views and in controllers/models.
SimpleCaptcha is available to be used with Rails 3 or above and also it provides the
backward compatibility with previous versions of Rails.

== For mongoid support

Just do

    include SimpleCaptcha::ModelHelpers
    
in your model, besides usual AR instructions

==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.

==Requirements

* {Ruby}[http://ruby-lang.org/] >= 1.8.7
* {Rails}[http://github.com/rails/rails] >= 3
* ImageMagick should be installed on your machine to use this plugin.
  visit http://www.imagemagick.org/script/index.php for more details.

==Installation

  gem "glebtv-simple_captcha"

or

  gem 'glebtv-simple_captcha', github: 'glebtv/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.

  rails generate simple_captcha

==Usage

===Controller Based

Add the following line in the file "app/controllers/application.rb"

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

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

====FormBuilder helper

  <%= form_for @user do |form| -%>
    ...
    <%= form.simple_captcha :label => "Enter numbers.." %>
    ...
  <% end -%>

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

  @user.valid_with_captcha?

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

  @user.save_with_captcha

===Formtastic integration
SimpleCaptcha detects if your use Formtastic and appends "SimpleCaptcha::CustomFormBuilder".

  <%= form.input :captcha, :as => :simple_captcha %>

==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"

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

* *code_type* - return numeric only if set to 'numeric'

===Global options

* *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'.

Create "rails_root/config/initializers/simple_captcha.rb"

  SimpleCaptcha.setup do |sc|
    # default: 100x28
    sc.image_size = '120x40'

    # default: 5
    sc.length = 6

    # default: simply_blue
    # possible values:
    # 'embosed_silver',
    # 'simply_red',
    # 'simply_green',
    # 'simply_blue',
    # 'distorted_black',
    # 'all_black',
    # 'charcoal_grey',
    # 'almost_invisible'
    # 'random'
    sc.image_style = 'simply_green'

    # default: low
    # possible values: 'low', 'medium', 'high', 'random'
    sc.distortion = 'medium'
  end

You can add your own style:

  SimpleCaptcha.setup do |sc|
    sc.image_style = 'mycaptha'
    sc.add_image_style('mycaptha', [
        "-background '#F4F7F8'",
        "-fill '#86818B'",
        "-border 1",
        "-bordercolor '#E0E2E3'"])
  end

You can provide the path where image_magick is installed as well:

  SimpleCaptcha.setup do |sc|
    sc.image_magick_path = '/usr/bin' # you can check this from console by running: which convert
  end


===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.
  /app/views/simple_captcha/_simple_captcha.erb

===View's Examples
====Controller Based Example

  <%= show_simple_captcha %>

  <%= show_simple_captcha(:label => "human authentication") %>

====Model Based 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

  class User < ActiveRecord::Base
    apply_simple_captcha
  end

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

==I18n

  simple_captcha:
    message:
      default: "Secret Code did not match with the Image"
      user: "The secret Image and code were different"

==The Original Author

Enjoy the simplest captcha implementation.

Author: Sur

Blog: http://expressica.com

Contact: sur.max@gmail.com

Plugin Homepage: http://expressica.com/simple_captcha

Plugin update for rails 3: http://github.com/galetahub

Any feedback/comment/issue/donation is welcome!