basis/furnace/recaptcha/recaptcha-docs.factor

   1 ! Copyright (C) 2009 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax http.server.filters kernel
   4 multiline furnace.actions furnace.alloy furnace.conversations ;
   5 IN: furnace.recaptcha
   6
   7 HELP: <recaptcha>
   8 { $values
   9     { "responder" "a responder" }
  10     { "obj" object }
  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: recaptcha-valid?
  18 { $var-description "Set to " { $link t } " if the user solved the last Recaptcha correctly." } ;
  19
  20 HELP: validate-recaptcha
  21 { $description "Validates a Recaptcha using the Recaptcha web service API." } ;
  22
  23 ARTICLE: "recaptcha-example" "Recaptcha example"
  24 "There are several steps to using the Recaptcha library."
  25 { $list
  26     { "Wrap the responder in a " { $link <recaptcha> } }
  27     { "Wrap the responder in a " { $link <conversations> } " if it is not already" }
  28     { "Ensure that there is a database connected, with the " { $link <alloy> } " word" }
  29     { "Start a conversation to move values between requests" }
  30     { "Add a handler calling " { $link validate-recaptcha } " in the " { $slot "submit" } " of the " { $link page-action } }
  31     { "Pass the conversation from your submit action using " { $link <continue-conversation> } }
  32     { "Put the chloe tag " { $snippet "<recaptcha/>" } " inside a form tag in the template for your " { $link page-action } }
  33 }
  34 $nl
  35 "Run this example vocabulary:"
  36 { $code
  37     "USE: furnace.recaptcha.example"
  38     "<recaptcha-app> main-responder set-global"
  39 } ;
  40
  41 ARTICLE: "furnace.recaptcha" "Recaptcha"
  42 "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
  43
  44 "The recaptcha responder is a " { $link filter-responder } " that wraps another responder. Set the " { $slot "domain" } ", " { $slot "public-key" } ", and " { $slot "private-key" } " slots of this responder to your Recaptcha account information." $nl
  45
  46 "Wrapping a responder with Recaptcha:"
  47 { $subsection <recaptcha> }
  48 "Validating recaptcha:"
  49 { $subsection validate-recaptcha }
  50 "Symbols set after validation:"
  51 { $subsection recaptcha-valid? }
  52 { $subsection recaptcha-error }
  53 { $subsection "recaptcha-example" } ;
  54
  55 ABOUT: "furnace.recaptcha"