README for captcha_service
===========================

Created by: Tracy Flynn
Date: 2009/01/25
Version: 0.6

captcha_service description
===========================

captcha_service is supplied as a Ruby Gem.

captcha_service provides a lightweight wrapping for various open and for-pay
on-line captcha services. Currently, a simple API is provided. Different captcha
services are selected at configuration time.

Currenty Mack, Rails and other application stacks are supported.

The following captcha providers are supported:

Captchator - http://captchator.com/ - (Free - limited volume)

Mollom - http://mollom.com (Commercial)
  Requires mollom gem Version 0.1.4
  Requires Private/Public keys from Mollom

captcha_service API
===================

There are three captcha_service API calls

captcha_service API: Get a provider instance
--------------------------------------------

provider = CaptchaService::Configurator.get_provider

captcha_service API: Get an image tag and a verification key
------------------------------------------------------------

captcha_key, captcha_image_tag = provider.image_tag

captcha_service API: Validate a captcha answer
----------------------------------------------

answer = provider.verify_answer(captcha_key,captcha_answer)

answer is a boolean - true/false

Sample Applications
===================

Sample applications showing how to implement the captcha_service APIs
are provided in ./spec/test_apps.

Configuration
=============

Create a YAML file 'captcha_service.yml' with the following format:

----------------------------------------------
captcha_service:
  :refresh_captcha:
    :enable_refresh_captcha: false
    :refresh_captcha_controller: 'minimal_application'
    :refresh_captcha_action: 'refresh_captcha'
  :default_provider: :mollom
  :providers:
    :captchator:
    :mollom:
      :private_key: 'f7c63d37d6a9ebdb62aca64688b38901'
      :public_key: '2c3f421dd5b32c6fe217dca701bc8972'
-----------------------------------------------

You can actually name it whatever you like.

Note: The Mollon keys are not valid. See description at top of README



For Configatron-based Systems - e.g. Mack
------------------------------------------

Place the file in a suitable location. For this discussion, place in
'./config/configurator/'.

In './config/configurator/default.rb' add the line:

configatron.captcha_service.configuration_filename = './config/configatron/captcha_service.yml'

If you need overrides by environment, then place these files in the same location,
using the standard naming conventions. E.g.

./config/configatron/captcha_service_production.yml
./config/configatron/captcha_service_development.yml
./config/configatron/captcha_service_test.yml

captcha_service will find these files and use their values to override the defaults.

For ApplicationConfiguration-based systems
------------------------------------------

(This section uses RAILS as an example)

Place the file in a suitable location. For this discussion, place in
'./config'.

In './config/application_configuration.yml' add the line:

captcha_service:
  :configuration_filename: './config/captcha_service.yml'

If you need overrides by environment, then place these files in the same location,
using the standard naming conventions. E.g.

./config/captcha_service_production.yml
./config/captcha_service_development.yml
./config/captcha_service_test.yml

captcha_service will find these files and use their values to override the defaults.

For other systems
-----------------

Set the environment variable:

CAPTCHA_SERVICE_CONFIGURATION_FILE

to point to the fully qualified nane of the captcha_service configuration file.

If you further specify the environment variable:

CAPTCHA_SERVICE_ENVIRONMENT

this will be used to find an additional environment-specific file in the same location
as the default captcha_service configuration file.

The file name is obtained by appending the environment name to the default configuration
file name with an underscore '-' as a separator.

viz: 

CAPTCHA_SERVICE_CONFIGURATION_FILE="/usr/apps/configuration/captcha_service.yml"
CAPTCHA_SERVICE_ENVIRONMENT='serious_production'

The environment-specific file will be named:

"usr/apps/configuration/captcha_service_serious_production_.yml"

Mack
-----

captcha_service knows about Mack environments and logging. It will log error messages
to 'Mack.logger'.


RAILS
-----

captcha_service knows about RAILS environments and logging. It will log error messages
to 'RAILS_DEFAULT_LOGGER'.

Other Environments
------------------

Currently, there is no support for 3rd party logging.

Ajax support for refreshing captcha
===================================

To enable the support for refreshing a captcha via an Ajax call

captcha_service:
  :refresh_captcha:
    :enable_refresh_captcha: true
    :refresh_captcha_controller: 'minimal_application'
    :refresh_captcha_action: 'refresh_captcha'
    
This clearly depends on a framework that follows Rails / Mack conventions

In the routes,

File: ./config/routes.rb

map.with_options :controller => 'minimal_application' do |msg|
  msg.refresh_captcha 'refresh_captcha', :action => 'refresh_captcha'
end

In the controller, a method similar to:

def refresh_captcha
  # Needs entry in routes
  # Needs an rjs partial in the correct location
  # Needs a partial to be called from the RJS in the correct location
  options = {:label => params['label_contents']}
  @captcha_div_contents = captcha_div_contents(options)
end

In the views:

File: ./app/views/minimal_application/refresh_captcha.rjs

page.replace_html("captcha_div", :partial => 'refresh_captcha_content', :object => @captcha_div_contents )

File: ./app/views/minimal_application/_refresh_captcha_content.html.erb

<%= @captcha_div_contents %>


Captcha Service Providers
=========================

The following Captcha Services providers are currently supported. Sample configurations
are also supplied:

Captchator
----------

http://captchator.com/

Configuration

captcha_service:
  :default_provider: :captchator
  :providers:
    :captchator:

Mollom
------

http://mollom.com

Configuration

captcha_service:
  :default_provider: :mollom
  :providers:
    :mollom:
      :private_key: 'f7c63d37d6a9ebdb62aca64688b38901'
      :public_key: '2c3f421dd5b32c6fe217dca701bc8972'

Changelog
---------

0.1 2008/12/1

Initial version

0.2 2008/12/7

Reorganized. Added provider for captchator

0.3 2008/12/7

Added provider for mollom

0.4 2008/12/7

Added error handling for existing providers

0.5 2008/12/8

Updated demo apps

0.6 2009/1/25

Added view and controller helper methods for Rails and Mack 
(thanks to Gerardo git://github.com/GrrrD/captcha_service.git)