basis/furnace/conversations/conversations-docs.factor

   1 USING: furnace.db furnace.sessions help.markup help.syntax http
   2 kernel urls words.symbol ;
   3 IN: furnace.conversations
   4
   5 HELP: <conversations>
   6 { $values
   7      { "responder" "a responder" }
   8      { "responder'" "a new responder" }
   9 }
  10 { $description "Creates a new " { $link conversations } " responder wrapping an existing responder." } ;
  11
  12 HELP: begin-conversation
  13 { $description "Starts a new conversation scope. Values can be stored in the conversation scope with " { $link cset } ", and the conversation can be continued with " { $link <continue-conversation> } "." } ;
  14
  15 HELP: end-conversation
  16 { $description "Ends the current conversation scope." } ;
  17
  18 HELP: <continue-conversation>
  19 { $values { "url" url } { "response" response } }
  20 { $description "Creates an HTTP response which redirects the client to the specified URL while continuing the conversation. Any values set in the current conversation scope will be visible to the resonder handling the URL." } ;
  21
  22 HELP: cget
  23 { $values { "key" symbol } { "value" object } }
  24 { $description "Outputs the value of a conversation variable." } ;
  25
  26 HELP: cset
  27 { $values { "value" object } { "key" symbol } }
  28 { $description "Sets the value of a conversation variable." } ;
  29
  30 HELP: cchange
  31 { $values { "key" symbol } { "quot" { $quotation ( old -- new ) } } }
  32 { $description "Applies the quotation to the old value of the conversation variable, and assigns the resulting value back to the variable." } ;
  33
  34 ARTICLE: "furnace.conversations" "Furnace conversation scope"
  35 "The " { $vocab-link "furnace.conversations" } " vocabulary implements conversation scope, which allows data to be passed between requests on a finer level of granularity than session scope."
  36 $nl
  37 "Conversation scope is used by form validation to pass validation errors between requests."
  38 $nl
  39 "To use conversation scope, wrap your responder in an conversation responder:"
  40 { $subsections <conversations> }
  41 "The conversations responder must be wrapped inside a session responder (" { $link <sessions> } "), which in turn must be wrapped inside a database persistence responder (" { $link <db-persistence> } "). The " { $vocab-link "furnace.alloy" } " vocabulary combines all of these responders into one."
  42 $nl
  43 "Managing conversation scopes:"
  44 { $subsections
  45     begin-conversation
  46     end-conversation
  47     <continue-conversation>
  48 }
  49 "Reading and writing conversation variables:"
  50 { $subsections
  51     cget
  52     cset
  53     cchange
  54 }
  55 "Note that conversation scope is serialized as part of the session, which means that only serializable objects can be stored there. See " { $link "furnace.sessions.serialize" } " for details." ;
  56
  57 ABOUT: "furnace.conversations"