validates_captcha 0.9.2 → 0.9.3

data/CHANGELOG.rdoc

@@ -1,3 +1,8 @@
-== 0.9.1 (September 27, 2009)
+== 0.9.3 (September 29, 2009)
+
+* Change API, include new Question provider, make it the default one
+
+
+== 0.9.2 (September 27, 2009)
 
 * Initial version

data/README.rdoc

@@ -1,12 +1,15 @@
 = Validates Captcha
 
-An image captcha verification approach for Rails apps, directly integrated into 
+A captcha verification approach for Rails apps, directly integrated into 
 ActiveRecord's validation mechanism and providing helpers for ActionController 
 and ActionView.
 
 RDoc documentation (including this README as start page) can be found at 
 http://m4n.github.com/validates_captcha
 
+Validates Captcha uses question/answer captchas by default. But you can 
+also use the built-in image captcha provider -- or implement your own.
+
 
 
 == Basic Usage
@@ -15,7 +18,7 @@ Validates Captcha extends ActiveRecord, ActionController and ActionView with
 helper methods that make it a snap to integrate captcha verification in your 
 Rails application.
 
-Step #1: Extend the form of your view with the necessary captcha code display 
+<b>Step #1:</b> Extend the form of your view with the necessary captcha display 
 and input logic.
 
   # app/views/comments/new.html.erb
@@ -32,8 +35,8 @@ and input logic.
     <!-- now something new: -->
     <p>
       <%= f.label :captcha %><br />
-      <%= f.captcha_image %>
-      <%= f.captcha_field %>
+      <%= f.captcha_challenge  # displays the question or image %>
+      <%= f.captcha_field      # displays the input field %>
     </p>
     
     <p>
@@ -41,7 +44,7 @@ and input logic.
     </p>
   <% end %>
 
-Step #2: Tell the controller that you want to validate 
+<b>Step #2:</b> Tell the controller that you want to validate 
 captchas.
 
   class CommentsController < ApplicationController
@@ -57,11 +60,11 @@ captchas.
 This activates captcha validation in every action of the controller 
 whenever an instance of class +Comment+ is saved.
 
-Step #3: There's no step three!
+<b>Step #3:</b> There's no step three!
 
 To summarize: Put the following in your view.
 
-  <%= f.captcha_image %>
+  <%= f.captcha_challenge %>
   <%= f.captcha_field %>
   
 And what you see below in the corresponding controller.
@@ -91,48 +94,39 @@ You can customize the validated class using the +validates_captcha_of+ method.
   end
   
 Two kinds of errors are added to the model if captcha validation fails: 
-+:blank+ if no captcha code is submitted and +:invalid+ if a captcha code 
-is submitted but does not match the code displayed on the captcha image. 
-You can localize the error messages for the captcha as you usually do 
-for the other attributes.
++:blank+ if no captcha solution is submitted and +:invalid+ if a captcha 
+solution is submitted but does not solve the captcha's challenge. You can 
+localize the error messages for the captcha as you usually do for the 
+other attributes.
 
   models:
     comment:
       attributes:
-        captcha:
+        captcha_solution:
           blank: 'must not be empty'
           invalid: 'does not match the code displayed on the image'
 
-What if the captcha's text is unreadable? There's also a form helper 
-method for captcha regeneration available. You can call it like this.
+What if the image captcha's text is unreadable or a user does not know the 
+correct answer to the captcha question? There's also a form helper method 
+for captcha regeneration available. You can call it like this.
 
   <p>
-    Captcha code unreadable? <%= f.regenerate_captcha_link %>
+    Don't know the answer? <%= f.regenerate_captcha_challenge_link %>
   </p>
 
-This generates an anchor tag that, when clicked, generates a new 
-captcha and updates the image. It makes an AJAX request to fetch a 
-new captcha code and updates the captcha image after the request is complete.
+This generates an anchor tag that, when clicked, generates a new captcha 
+challenge and updates the display. It makes an AJAX request to fetch a 
+new challenge and updates the question/image after the request is complete.
 
-+regenerate_captcha_link+ internally calls Rails' #link_to_remote helper 
-method. So it relies on the Prototype javascript framework to be available 
-on the page.
++regenerate_captcha_challenge_link+ internally calls Rails' +link_to_remote+
+helper method. So it relies on the Prototype javascript framework to be 
+available on the page.
 
-The anchor's text defaults to 'Regenerate Captcha'. You can set this to 
+The anchor's text defaults to 'New question' (question challenge) and 
+'Regenerate Captcha' (image challenge) respectively. You can set this to 
 a custom value by providing a +:text+ key in the options hash.
 
-  <%= f.regenerate_captcha_link :text => 'Another captcha, please' %>
-
-By default, captchas have a length of 6 characters and the text displayed 
-on the captcha image is created by randomly selecting characters from a 
-predefined alphabet constisting of visually distinguishable letters and digits.
-
-The number of characters and the alphabet used when generating strings can 
-be customized. Just put the following in a Rails initializer and adjust the 
-values to your needs.
-
-  ValidatesCaptcha::StringGenerator::Simple.alphabet = '01'
-  ValidatesCaptcha::StringGenerator::Simple.length = 8
+  <%= f.regenerate_captcha_challenge_link :text => 'Another captcha, please' %>
 
 Apart from controllers, you can activate captcha validation for a model 
 using the class level +with_captcha_validation+ method added to 
@@ -146,28 +140,67 @@ ActiveRecord::Base.
 This activates captcha validation on entering the block and deactivates it 
 on leaving the block.
 
-Two new attribute like methods are added to ActiveRecord: +captcha+ and 
-+encrypted_captcha+.  Those are made +attr_accessible+.  The latter is 
-initialized to a randomly generated and encrypted captcha code on 
-instantation. 
+Two new attribute-like methods are added to ActiveRecord: +captcha_challenge+ 
+and +captcha_solution+.  Those are made +attr_accessible+.  The former is 
+initialized to a randomly generated captcha challenge on instantiation. 
+
+For a record to be valid, the value assigned to +captcha_solution=+ must 
+solve the return value of +captcha_challenge+.  Within a +with_captcha_validation+ 
+block, calling +valid?+ (as is done by +save+, +update_attributes+, etc.) 
+will also validate the value of +captcha_solution+ against +captcha_challenge+.  
+Outside +with_captcha_validation+, no captcha validation is performed.
+
+
+
+== Question/answer challange captchas (default provider)
+
+You can set the captcha provider to use question/answer challenges with 
+the code below. It is best to put this in a Rails initializer.
+
+  ValidatesCaptcha.provider = ValidatesCaptcha::Provider::Question.new # this is the default
+
+If you want to replace the few default questions and answers, here's how 
+to do it.
 
-For a record to be valid, the value assigned to +captcha=+ must match the 
-decryption of the return value of +encrypted_captcha+.  Within a 
-+with_captcha_validation+ block, calling +valid?+ (as is done by +save+, 
-+update_attributes+, etc.) will also validate the value of +captcha+ 
-against the +encrypted_captcha+.  Outside +with_captcha_validation+, no 
-captcha validation is performed.
+  ValidatesCaptcha::Provider::Question.questions_and_answers = {
+    "What's the opposite of bad?" => "good",
+    "What are the initials of the creator of Rails?" => "DHH",
+    "What's the sum of 3 and four?" => ["7", "seven"],
+    ... }
+
+
+
+== Image challenge captchas
+
+You can set the captcha provider to use image challenges with 
+the code below. It is best to put this in a Rails initializer.
+
+  ValidatesCaptcha.provider = ValidatesCaptcha::Provider::Image.new
+
+By default, image captchas have a length of 6 characters and the text displayed 
+on the captcha image is created by randomly selecting characters from a 
+predefined alphabet constisting of visually distinguishable letters and digits.
+
+The number of characters and the alphabet used when generating strings can 
+be customized. Just put the following in a Rails initializer and adjust the 
+values to your needs.
+
+  ValidatesCaptcha::StringGenerator::Simple.alphabet = '01'
+  ValidatesCaptcha::StringGenerator::Simple.length = 8
 
 
 
 == Extensibility
 
+Don't like the built-in challenges? It's easy to extend them or to implement 
+your own.
+
 Validates Captcha delegates tasks like string and image generation, 
 encryption/decryption of captcha codes, and responding to captcha requests 
 to dedicated backend classes.
 
-Those classes can easily be replaced by your custom implementations.  So 
-you can achieve stronger encryption, can use a word list as captcha text 
+Those classes can easily be replaced with your custom implementations.  So 
+you can achieve stronger encryption, can use a word list as image captcha text 
 generation source, or can replace the captcha image generator with one 
 that creates images that are harder to crack.
 
@@ -176,7 +209,10 @@ Please see the documentation of the following classes for further information.
 * ValidatesCaptcha::StringGenerator::Simple
 * ValidatesCaptcha::ReversibleEncrypter::Simple
 * ValidatesCaptcha::ImageGenerator::Simple
-* ValidatesCaptcha::Middleware::Simple
+
+Or you can implement a custom captcha challenge provider and assign it to 
+ValidatesCaptcha#provider=. See the documentation on ValidatesCaptcha::Provider
+for an example.
 
 
 
@@ -185,8 +221,8 @@ Please see the documentation of the following classes for further information.
 Using a Rack middleware to speed up the request/response cycle when fetching 
 captcha images, Validates Captcha requires Rails version 2.3 or greater.
 
-The default captcha image generator uses ImageMagick's +convert+ command to 
-create the captcha.  So a recent and properly configured version of ImageMagick 
+The image captcha provider uses ImageMagick's +convert+ command to create 
+the captcha.  So a recent and properly configured version of ImageMagick 
 must be installed on the system.  The version used while developing was 6.4.5.  
 But you are not bound to ImageMagick.  If you want to provide a custom image 
 generator, take a look at the documentation for 

data/lib/validates_captcha.rb

@@ -22,17 +22,11 @@
 #++
 
 
-# This module contains the getters and setters for the backend classes: 
-# image/string generator, reversible encrypter, and Rack middleware. This 
-# allows you to replace them with your custom implementations. For more 
+# This module contains the getter and setter for the captcha provider. 
+# This allows you to replace it with your custom implementation. For more 
 # information on how to bring Validates Captcha to use your own 
 # implementation instead of the default one, consult the documentation 
-# for the specific default class.
-# 
-# This module also contains convenience wrapper methods for all the 
-# methods provided by the configured backend classes. These wrapper 
-# methods form the API that is visible to the outside world and that 
-# all backend classes use for internal communication.
+# for the default provider.
 module ValidatesCaptcha
   autoload :ModelValidation, 'validates_captcha/model_validation'
   autoload :ControllerValidation, 'validates_captcha/controller_validation'
@@ -41,8 +35,9 @@ module ValidatesCaptcha
   autoload :TestCase, 'validates_captcha/test_case'
   autoload :VERSION, 'validates_captcha/version'
   
-  module ImageGenerator
-    autoload :Simple, 'validates_captcha/image_generator/simple'
+  module Provider
+    autoload :Question, 'validates_captcha/provider/question'
+    autoload :Image, 'validates_captcha/provider/image'
   end
   
   module StringGenerator
@@ -53,117 +48,27 @@ module ValidatesCaptcha
     autoload :Simple, 'validates_captcha/reversible_encrypter/simple'
   end
   
-  module Middleware
-    autoload :Simple, 'validates_captcha/middleware/simple'
-  end  
+  module ImageGenerator
+    autoload :Simple, 'validates_captcha/image_generator/simple'
+  end
   
-  @@image_generator = nil
-  @@string_generator = nil
-  @@reversible_encrypter = nil
-  @@middleware = nil
+  @@provider = nil
   
   class << self
-    # Returns ValidatesCaptcha's current version number.
+    # Returns Validates Captcha's current version number.
     def version
       ValidatesCaptcha::VERSION::STRING
     end
     
-    # Returns the current captcha image generator. Defaults to an 
-    # instance of the ValidatesCaptcha::ImageGenerator::Simple class.
-    def image_generator
-      @@image_generator ||= ImageGenerator::Simple.new
-    end
-
-    # Sets the current captcha image generator. Used to set a custom 
-    # image generator.
-    def image_generator=(generator)
-      @@image_generator = generator
-    end
-    
-    # Returns the current captcha string generator. Defaults to an 
-    # instance of the ValidatesCaptcha::StringGenerator::Simple class.
-    def string_generator
-      @@string_generator ||= StringGenerator::Simple.new
-    end
-
-    # Sets the current captcha string generator. Used to set a 
-    # custom string generator.
-    def string_generator=(generator)
-      @@string_generator = generator
-    end
-    
-    # Returns the current captcha reversible encrypter. Defaults to an 
-    # instance of the ValidatesCaptcha::ReversibleEncrypter::Simple class.
-    def reversible_encrypter
-      @@reversible_encrypter ||= ReversibleEncrypter::Simple.new
-    end
-
-    # Sets the current captcha reversible encrypter. Used to set a 
-    # custom reversible encrypter.
-    def reversible_encrypter=(encrypter)
-      @@reversible_encrypter = encrypter
-    end
-    
-    # Returns the current captcha middleware. Defaults to the 
-    # ValidatesCaptcha::Middleware::Simple class.
-    def middleware
-      @@middleware ||= Middleware::Simple.new
+    # Returns the current captcha challenge provider. Defaults to an instance of 
+    # the ValidatesCaptcha::Provider::Question class.
+    def provider
+      @@provider ||= Provider::Question.new
     end
 
-    # Sets the current captcha middleware. Used to set a custom 
-    # middleware.
-    def middleware=(middleware)
-      @@middleware = middleware
-    end
-    
-    # Randomly generates a string which can be used as the code 
-    # displayed on captcha images. This method internally calls 
-    # +string_generator.generate+.
-    def generate_captcha_code
-      string_generator.generate
-    end
-    
-    # Returns the image data of the generated captcha image. This 
-    # method internally calls +image_generator.generate+.
-    def generate_captcha_image(code)
-      image_generator.generate(code)
-    end
-    
-    # Returns the image file extension of the captcha images. This 
-    # method internally calls +image_generator.image_file_extension+.
-    def captcha_image_file_extension
-      image_generator.image_file_extension
-    end
-    
-    # Returns the image mime type of the captcha images. This 
-    # method internally calls +image_generator.image_mime_type+.
-    def captcha_image_mime_type
-      image_generator.image_mime_type
-    end
-    
-    # Returns the encryption of a cleartext captcha code. This 
-    # method internally calls +reversible_encrypter.encrypt+.
-    def encrypt_captcha_code(code)
-      reversible_encrypter.encrypt(code)
-    end
-    
-    # Returns the decryption of an encrypted captcha code. This 
-    # method internally calls +reversible_encrypter.decrypt+.
-    def decrypt_captcha_code(encrypted_code)
-      reversible_encrypter.decrypt(encrypted_code)
-    end
-    
-    # Returns the captcha image path for a given encrypted code. This 
-    # method internally calls +middleware.image_path+.
-    def captcha_image_path(encrypted_code)
-      middleware.image_path(encrypted_code)
-    end
-    
-    # Returns the path that is used when requesting the regeneration 
-    # of a captcha image. This method internally calls 
-    # +middleware.regenerate_path+.
-    def regenerate_captcha_path
-      middleware.regenerate_path
+    # Sets the current captcha challenge provider. Used to set a custom provider.
+    def provider=(provider)
+      @@provider = provider
     end
   end
 end

data/lib/validates_captcha/form_builder.rb

@@ -1,15 +1,15 @@
 module ValidatesCaptcha
   module FormBuilder #:nodoc:
-    def captcha_image(options = {}) #:nodoc:
-      @template.captcha_image @object_name, options.merge(:object => @object)
+    def captcha_challenge(options = {}) #:nodoc:
+      @template.captcha_challenge @object_name, options.merge(:object => @object)
     end
     
     def captcha_field(options = {}) #:nodoc:
       @template.captcha_field @object_name, options.merge(:object => @object)
     end
     
-    def regenerate_captcha_link(options = {}, html_options = {}) #:nodoc:
-      @template.regenerate_captcha_link @object_name, options.merge(:object => @object), html_options
+    def regenerate_captcha_challenge_link(options = {}, html_options = {}) #:nodoc:
+      @template.regenerate_captcha_challenge_link @object_name, options.merge(:object => @object), html_options
     end
   end
 end

data/lib/validates_captcha/form_helper.rb

@@ -1,50 +1,38 @@
 module ValidatesCaptcha
   module FormHelper
-    # Returns an img tag with the src attribute pointing to the captcha image url. 
+    # Returns the captcha challenge. 
     #
-    # Internally calls Rails' #image_tag helper method, passing the +options+ 
-    # argument.
-    def captcha_image(object_name, options = {})
+    # Internally calls the +render_challenge+ method of ValidatesCaptcha#provider.
+    def captcha_challenge(object_name, options = {})
+      options.symbolize_keys!
+      
       object = options.delete(:object)
-      src = ValidatesCaptcha.captcha_image_path(object.encrypted_captcha)
       sanitized_object_name = object_name.to_s.gsub(/\]\[|[^-a-zA-Z0-9:.]/, "_").sub(/_$/, "")
       
-      options[:alt] ||= 'CAPTCHA'
-      options[:id] = "#{sanitized_object_name}_captcha_image"
-      
-      image_tag src, options
+      ValidatesCaptcha.provider.render_challenge sanitized_object_name, object, options
     end
     
-    # Returns an input tag of the "text" type tailored for entering the captcha code.
+    # Returns an input tag of the "text" type tailored for entering the captcha solution.
     #
     # Internally calls Rails' #text_field helper method, passing the +object_name+ and 
     # +options+ arguments.
     def captcha_field(object_name, options = {})
       options.delete(:id)
       
-      hidden_field(object_name, :encrypted_captcha, options) + text_field(object_name, :captcha, options)
+      hidden_field(object_name, :captcha_challenge, options) + text_field(object_name, :captcha_solution, options)
     end
     
-    # Returns an anchor tag that makes an AJAX request to fetch a new captcha code and updates 
-    # the captcha image after the request is complete.
+    # By default, returns an anchor tag that makes an AJAX request to fetch a new captcha challenge and updates 
+    # the current challenge after the request is complete.
     # 
-    # Internally calls Rails' #link_to_remote helper method, passing the +options+ and 
-    # +html_options+ arguments. So it relies on the Prototype javascript framework 
-    # to be available on the web page.
-    #
-    # The anchor text defaults to 'Regenerate Captcha'. You can set this to a custom value 
-    # providing a +:text+ key in the +options+ hash.
-    def regenerate_captcha_link(object_name, options = {}, html_options = {})
+    # Internally calls +render_regenerate_challenge_link+ method of ValidatesCaptcha#provider.
+    def regenerate_captcha_challenge_link(object_name, options = {}, html_options = {})
       options.symbolize_keys!
       
       object = options.delete(:object)
-      text = options.delete(:text) || 'Regenerate Captcha'      
       sanitized_object_name = object_name.to_s.gsub(/\]\[|[^-a-zA-Z0-9:.]/, "_").sub(/_$/, "")
       
-      url = ValidatesCaptcha.regenerate_captcha_path
-      success = "var result = request.responseJSON; $('#{sanitized_object_name}_captcha_image').src = result.captcha_image_path; $('#{sanitized_object_name}_encrypted_captcha').value = result.encrypted_captcha_code;"
-      
-      link_to_remote text, options.reverse_merge(:url => url, :method => :get, :success => success), html_options
+      ValidatesCaptcha.provider.render_regenerate_challenge_link sanitized_object_name, object, options, html_options
     end
   end
 end