basis/furnace/asides/asides-docs.factor

   1 USING: furnace.db furnace.redirection furnace.sessions
   2 help.markup help.syntax http urls ;
   3 IN: furnace.asides
   4
   5 HELP: <asides>
   6 { $values
   7      { "responder" "a responder" }
   8      { "responder'" "a new responder" }
   9 }
  10 { $description "Creates a new " { $link asides } " responder wrapping an existing responder." } ;
  11
  12 HELP: begin-aside
  13 { $values { "url" url } }
  14 { $description "Begins an aside. When the current action returns a " { $link <redirect> } ", the redirect will have query parameters which reference the current page via an opaque handle." } ;
  15
  16 HELP: end-aside
  17 { $values { "default" url } { "response" response } }
  18 { $description "Ends an aside. If an aside is currently active, the response redirects the client " } ;
  19
  20 ARTICLE: "furnace.asides" "Furnace asides"
  21 "The " { $vocab-link "furnace.asides" } " vocabulary provides support for sending a user to a page which can then return to the former location."
  22 $nl
  23 "To use asides, wrap your responder in an aside responder:"
  24 { $subsections <asides> }
  25 "The asides 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."
  26 $nl
  27 "Saving the current page in an aside which propagates through " { $link <redirect> } " responses:"
  28 { $subsections begin-aside }
  29 "Returning from an aside:"
  30 { $subsections end-aside }
  31 "Asides are used by " { $vocab-link "furnace.auth.login" } "; when the client requests a protected page, an aside begins and the client is redirected to a login page. Upon a successful login, the aside ends and the client returns to the protected page. If the client directly visits the login page and logs in, there is no current aside, so the client is sent to the default URL passed to " { $link end-aside } ", which in the case of login is the root URL." ;
  32
  33 ABOUT: "furnace.asides"