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