Skip to content

Latest commit

 

History

History
218 lines (147 loc) · 5.75 KB

README.rdoc

File metadata and controls

218 lines (147 loc) · 5.75 KB
Raw

SimpleCaptcha ↑

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 Rails 3 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.

Requirements ↑

Installation ↑

gem 'simple_captcha', :git => 'git://github.com/galetahub/simple-captcha.git'

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

rake db:migrate

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"

Who’s who? ↑

Enjoy the simplest captcha implementation.

Author: Sur

Blog: expressica.com

Contact: [email protected]

Plugin Homepage: expressica.com/simple_captcha

Plugin update for rails 3: github.com/galetahub

Any feedback/comment/issue/donation is welcome!