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

http://scruptious-social-networking.googlecode.com/ · Unknown · 123 lines · 84 code · 39 blank · 0 comment · 0 complexity · 4dc31a0c659ba852b474d3c5dfd19d8f MD5 · raw file

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