basis/furnace/recaptcha/recaptcha-docs.factor

   1 ! Copyright (C) 2009 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: furnace.actions furnace.alloy help.markup help.syntax
   4 http.server.filters ;
   5 IN: furnace.recaptcha
   6
   7 HELP: <recaptcha>
   8 { $values
   9     { "responder" "a responder" }
  10     { "recaptcha" recaptcha }
  11 }
  12 { $description "A " { $link filter-responder } " wrapping another responder. Set the domain, public, and private keys using the key you get by registering with recaptcha." } ;
  13
  14 HELP: recaptcha-error
  15 { $var-description "Set to the error string returned by the recaptcha server." } ;
  16
  17 HELP: validate-recaptcha
  18 { $description "Validates a recaptcha using the recaptcha web service API." } ;
  19
  20 ARTICLE: "recaptcha-example" "Recaptcha example"
  21 "There are several steps to using the recaptcha library."
  22 { $list
  23     { "Wrap the responder in a " { $link <recaptcha> } }
  24     { "Wrap the responder in an " { $link <alloy> } " if it is not already, to enable conversations and database access" }
  25     { "Call " { $link validate-recaptcha } " from the " { $slot "validate" } " slot of the " { $link action } }
  26     { "Put the chloe tag " { $snippet "<recaptcha/>" } " inside a form tag in the template served by your " { $link action } }
  27 }
  28 $nl
  29 "There is an example web app using recaptcha support:"
  30 { $code
  31     "USING: furnace.recaptcha.example http.server ;"
  32     "<recaptcha-app> main-responder set-global"
  33     "8080 httpd"
  34 } ;
  35
  36 ARTICLE: "furnace.recaptcha" "Recaptcha support for Furnace"
  37 "The " { $vocab-link "furnace.recaptcha" } " vocabulary implements support for the recaptcha. Recaptcha is a web service that provides the user with a captcha, a test that is easy to solve by visual inspection, but hard to solve by writing a computer program. Use a captcha to protect forms from abusive users." $nl
  38
  39 "The recaptcha responder is a " { $link filter-responder } " that wraps another responder. Set the " { $slot "domain" } ", " { $slot "site-key" } ", and " { $slot "secret-key" } " slots of this responder to your recaptcha account information." $nl
  40
  41 "Wrapping a responder with recaptcha support:"
  42 { $subsections <recaptcha> }
  43 "Validating recaptcha:"
  44 { $subsections validate-recaptcha }
  45 "Symbol set after validation:"
  46 { $subsections recaptcha-error }
  47 "An example:"
  48 { $subsections "recaptcha-example" } ;
  49
  50 ABOUT: "furnace.recaptcha"