How To add BotDetect CAPTCHA protection to Ruby on Rails forms

Important note: since this sample uses a version of BotDetect CAPTCHA implemented as a COM component, both your servers and development machines must use a Windows family OS. At the moment we don't support Ruby on Rails websites running on other operating systems.

Prerequisites:

• Ruby 1.8.4+
• Rails 1.1
• a Windows OS
• BotDetect 2.0 ASP CAPTCHA

Start by downloading the Sample BotDetect CAPTCHA Ruby on Rails project.

• Add the "LanapBotDetect" action to a Controller
• Render the CAPTCHA image in a View
• Use the sound CAPTCHA in a View
• Validate the user input

Step 1: Add the "LanapBotDetect" action to a Controller

In the controller class of the page where you want to use BotDetect CAPTCHA protection, add the require statement and the LanapBotDetect action definition, as in the sample_controller.rb:

require 'win32ole'

class SampleController < ApplicationController
  
  def LanapBotDetect
    
    if(!params["Command"].nil?)

      @command = params["Command"].to_s
      @captcha = WIN32OLE.new('Lanap.BotDetect')

      if(!params["TextStyle"].nil?)
        @captcha.TextStyle = params["TextStyle"].to_s
      end

      if(!params["ImageWidth"].nil?)
        @captcha.ImageWidth = params["ImageWidth"].to_s
      end

      if(!params["ImageHeight"].nil?)
        @captcha.ImageHeight = params["ImageHeight"].to_s
      end

      if(!params["CodeLength"].nil?)
        @captcha.CodeLength = params["CodeLength"].to_s
      end

      if(!params["CodeType"].nil?)
        @captcha.CodeType = params["CodeType"].to_s
      end

      if(!params["Format"].nil?)
        @captcha.Format = params["Format"].to_s
      end

      if("CreateImage" == @command)
        @buffer = @captcha.CreateImage.pack("c*")
        session[:code] = @captcha.GetValue

        @type = "image/jpeg"
        send_data(@buffer, :filename => "captcha.jpg", 
          :type => @type, :disposition => "inline")

      elsif("CreateSound" == @command)
        @buffer = 
        @captcha.CreateSoundFromCode(session[:code]).pack("c*")

        @type = "audio/x-wav"
        send_data(@buffer, :filename => "captcha.wav", 
          :type => @type, :disposition => "inline")
      end
			
    end
		
  end
	
end

[back to top]

Step 2: Render the CAPTCHA image in a View

The simplest way to show a CAPTCHA image (using the default parameters) in your .rhtml View definition is to use an <img> tag like this one:

<img src="<%= url_for(:action => "LanapBotDetect") + 
  '?Command=CreateImage' %>" alt="CAPTCHA image" />

If you have BotDetect installed and everything is configured correctly, this will result in a picture similar to this being rendered:

Setting additional CAPTCHA image properties

If you want to set aditional properties (like choosing the image size, type etc...) just specify them as querystring parameters. For example:

<img src="<%= url_for(:action => "LanapBotDetect") + 
  'Command=CreateImage&TextStyle=28&ImageWidth=300&imageHeight=
    40&CodeLength=7&CodeType=1&Format=PNG" alt="CAPTCHA image" />

The resulting picture would look like this:

All other parameters (besides ?Command=CreateImage) are optional, and if a parameter is not specified, the default value is used.

For example, the TextStyle parameter specifies the CAPTCHA image drawing algorithm used (out of 50 BotDetect CAPTCHA algorithms). You can find the list of all valid values, examples of use and screenshots for this parameter at theTextStyle reference page.

You can find detailed information about all available CAPTCHA parameters in the BotDetect Component Interface reference documentation.

[back to top]

Step 3: Use the sound CAPTCHA in a View

If you want to also use a sound CAPTCHA to improve the accessiblity of your page, the simplest way to access it is as follows:

<a href="<%= url_for(:action => "LanapBotDetect") + 
  '?Command=CreateSound"> 
    <img src="speaker.gif" alt="Play Sound" style="border:0;" />
</a>

A speaker icon (it can be found with the samples coming with the installation) is used as a link which invokes the sound CAPTCHA playback. You could also use a text link (e.g. "Play Sound") or a different picture if that's more suitable for your application.

[back to top]

Step 4: Validate the user input

In a typical CAPTCHA usage scenario, you will have a text box on the page to receive the user's input, and compare it's submitted value to the code rendered in the CAPTCHA image.

<div id="ValidationDiv">
  <%= text_field("Captcha", "TextBoxUserCode", "size" => 20, 
    "id" => "TextBoxUserCode" ) %>
  <%= submit_tag("Validate") %>

  <% if params.include?("Captcha") %>
    <% if (session[:code] and 
      params["Captcha"]["TextBoxUserCode"].to_s.upcase == 
      session[:code]) %>
        <span id='MessageCorrectLabel'>Correct!</span>
    <% else %>
      <span id='MessageIncorrectLabel'>Incorrect!</span>
    <% end %>
  <% end %>
</div>

[back to top]