Permalink
Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
225 lines (167 sloc) 7.87 KB
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!
===========================================================================================