mod_recaptcha Readme File
=========================

Author: François Cardinaux, CH 1207 Geneva (http://bit.ly/qTaona)

Overview of the current folder: 
  * The current folder is dedicated to the mod_recaptcha module for Zotonic 
    (http://www.zotonic.com)
  * It contains all files that are necessary to this project
  * There is no symlink of any sort to external resources

Credits
-------

The following references have been helpful to write this module: 
  * the reCaptcha API: http://code.google.com/apis/recaptcha/
  * How to make HTTP post: 
    http://erlangexamples.com/2009/02/24/how-to-make-http-post/
  * recaptcha-erlang: http://code.google.com/p/recaptcha-erlang/

Installation
------------

 1. Copy this folder to /path/to/zotonic/modules/
 2. Start Zotonic
 3. Open your site with a web browser and log in as admin
 4. Open the amnistration interface (http://<your site>/admin)
 5. Enable the Recaptcha module: go "Modules", find the "Recaptcha" module and 
    click on "activate"
 6. Go to "System" and click on "rescan modules"
 
Configuration
-------------

 1. Go to http://www.google.com/recaptcha and follow the instructions to create
    your Recaptcha keys (one public key and one private key)
    
 2. Open the amnistration interface (http://<your site>/admin)
 
 3. Go to "Config" and click on "make a new config setting"
 
        Module: mod_recaptcha
        Key:    public_key
        Value:  <your public key>

 4. Always in "Config", click on "make a new config setting" again
 
        Module: mod_recaptcha
        Key:    private_key
        Value:  <your private key>
        
Using mod_recaptcha on signup forms
-----------------------------------

    Edit your signup form template (typically signup.tpl) and add the following
    line where you want the captcha to appear: 
 
        {% include "_captcha.tpl" %}

Using mod_recaptcha on other forms
----------------------------------

 1. Edit your form template and add the following line where you want the 
    captcha to appear: 
 
        {% include "_captcha.tpl" %}

 2. Add the following code to your form processing: 
 
        ...
        case mod_recaptcha:check_recaptcha(Context) of
            ok -> 
                process_form(Context);
            {error, Error} ->
                display_error_message(Error)
        end,
        ...
        
        % Implementation not shown here
        process_form(_Context) ->
            todo.
 
        % Implementation not shown here
        display_error_message(_Error) ->
            todo.
            
 3. Recompile Zotonic
 
Disabling recaptcha with an observer
------------------------------------

    Why
    ...

    By default, recaptcha is enabled if and only if the module mod_recaptcha is 
    enabled. 
    
    In some situations however, you may want to disable recaptcha 
    programmatically, depending on some variables of your system. For instance, 
    suppose that you are starting a membership-based website, and that during 
    the initial period you want to restrict the use of your signup form to 
    invited people only. In this case, you don't want to annoy them with a 
    captcha, since their e-mail address is checked against a control list 
    anyway. However, you want that recaptcha remains enabled on other forms
    of the site, e.g. your contact form.
    
    How
    ...

    The simplest way to program this is to use the observer 
    observe_recaptcha_enabled/3.
    
 1. Edit your main site module (/path/to/zotonic/priv/sites/mysite/mysite.erl)
    and add the following lines: 
    
        -export([observe_recaptcha_enabled/3]).
        
        observe_recaptcha_enabled(recaptcha_enabled, Acc, Context) ->
            case Acc of
                true -> 
                    InviationOnly = is_signup_upon_invitation_only(),
                    Path = m_req:get(path, Context),
                    
                    case {InviationOnly, Path} of
                        {true, "/signup"} -> 
                            false; % This disables recaptcha
                            
                        _ ->
                            true
                    end;
                
                _ -> Acc
            end.
            
        is_signup_upon_invitation_only() ->
            true. % You may read this value from a configuration register
            
 2. Recompile Zotonic