/vendor/plugins/ambethia-recaptcha-f86ef39/README.rdoc
Unknown | 123 lines | 84 code | 39 blank | 0 comment | 0 complexity | 4dc31a0c659ba852b474d3c5dfd19d8f MD5 | raw file
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