/vendor/plugins/ambethia-recaptcha-f86ef39/README.rdoc

  1= reCAPTCHA
  2
  3Author::    Jason L Perry (http://ambethia.com)
  4Copyright:: Copyright (c) 2007 Jason L Perry
  5License::   {MIT}[http://creativecommons.org/licenses/MIT/]
  6Info::      http://ambethia.com/recaptcha
  7Git::       http://github.com/ambethia/recaptcha/tree/master
  8Bugs::      http://github.com/ambethia/recaptcha/issues
  9
 10This plugin adds helpers for the {reCAPTCHA API}[http://recaptcha.net]. In your
 11views you can use the +recaptcha_tags+ method to embed the needed javascript,
 12and you can validate in your controllers with +verify_recaptcha+.
 13
 14Beforehand you need to configure Recaptcha with your custom private and public
 15key. You may find detailed examples below. Exceptions will be raised if you
 16call these methods and the keys can't be found.
 17
 18== About this fork
 19
 20This fork tries to introduces a more convenient way to configure recaptcha's
 21settings. The API will be inspired by {Thoughtbot's
 22Hoptoad}[http://robots.thoughtbot.com/post/344833329/mygem-configure-block].
 23
 24== Rails Installation
 25
 26reCAPTCHA for Rails can be installed as a gem:
 27
 28  config.gem "recaptcha", :lib => "recaptcha/rails"
 29
 30Or, as a standard rails plugin:
 31
 32  script/plugin install git://github.com/ambethia/recaptcha.git
 33
 34== Merb Installation
 35
 36reCAPTCHA can also be used in a Merb application when installed as a gem:
 37
 38  dependency "alm-recaptcha", ">=0.2.2.1", :require_as => "recaptcha/merb"
 39
 40Initial Merb compatability funded by ALM Labs.
 41
 42== Setting up your API Keys
 43
 44There are multiple ways to setup your reCAPTCHA API key once you
 45{obtain}[http://recaptcha.net/whyrecaptcha.html] a pair.
 46
 47=== Recaptcha.configure
 48
 49You may use the block style configuration. The following code could be placed
 50into a +config/initializers/recaptcha.rb+ when used in a Rails project.
 51
 52  Recaptcha.configure do |config|
 53    config.public_key  = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
 54    config.private_key = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
 55  end
 56
 57This way, you may also set additional options to fit recaptcha into your
 58deployment environment.
 59
 60=== Shell environment
 61
 62Or, you can keep your keys out of your code base by exporting the following
 63environment variables. You might do this in the .profile/rc, or equivalent for
 64the user running your application:
 65
 66  export RECAPTCHA_PUBLIC_KEY  = '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
 67  export RECAPTCHA_PRIVATE_KEY = '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
 68
 69=== Per call
 70
 71You can also pass in your keys as options at runtime, for example:
 72
 73  recaptcha_tags :public_key => '6Lc6BAAAAAAAAChqRbQZcn_yyyyyyyyyyyyyyyyy'
 74
 75and later,
 76
 77  verify_recaptcha :private_key => '6Lc6BAAAAAAAAKN3DRm6VA_xxxxxxxxxxxxxxxxx'
 78
 79This option might be useful, if the same code base is used for multiple
 80reCAPTCHA setups.
 81
 82== +recaptcha_tags+
 83
 84Some of the options available:
 85
 86<tt>:ssl</tt>::         Uses secure http for captcha widget (default +false+)
 87<tt>:noscript</tt>::    Include <noscript> content (default +true+)
 88<tt>:display</tt>::     Takes a hash containing the +theme+ and +tabindex+ options per the API. (default +nil+)
 89<tt>:ajax</tt>::        Render the dynamic AJAX captcha per the API. (default +false+)
 90<tt>:public_key</tt>::  Your public API key, takes precedence over the ENV variable (default +nil+)
 91<tt>:error</tt>::       Override the error code returned from the reCAPTCHA API (default +nil+)
 92
 93You can also override the html attributes for the sizes of the generated +textarea+ and +iframe+
 94elements, if CSS isn't your thing. Inspect the source of +recaptcha_tags+ to see these options.
 95
 96== +verify_recaptcha+
 97
 98This method returns +true+ or +false+ after processing the parameters from the reCAPTCHA widget. Why
 99isn't this a model validation? Because that violates MVC. Use can use it like this, or how ever you
100like. Passing in the ActiveRecord object is optional, if you do--and the captcha fails to verify--an
101error will be added to the object for you to use.
102
103Some of the options available:
104
105<tt>:model</tt>::       Model to set errors
106<tt>:attribute</tt>::   Model attribute to receive errors (default :base)
107<tt>:message</tt>::     Custom error message
108<tt>:private_key</tt>:: Your private API key, takes precedence over the ENV variable (default +nil+).
109<tt>:timeout</tt>::     The number of seconds to wait for reCAPTCHA servers before give up. (default +3+)
110
111  respond_to do |format|
112    if verify_recaptcha(:model => @post, :message => "Oh! It's error with reCAPTCHA!") && @post.save
113      # ...
114    else
115      # ...
116    end
117  end
118
119== TODO
120* Remove Rails/ActionController dependencies
121* Framework agnostic
122* Add some helpers to use in before_filter and what not
123* Better documentation