basis/furnace/utilities/utilities-docs.factor

   1 USING: assocs help.markup help.syntax kernel
   2 quotations sequences strings urls xml.data http ;
   3 IN: furnace.utilities
   4
   5 HELP: adjust-redirect-url
   6 { $values { "url" url } { "url'" url } }
   7 { $description "Adjusts a redirection URL by filtering the URL's query parameters through the " { $link modify-redirect-query } " generic word on every responder involved in handling the current request." } ;
   8
   9 HELP: adjust-url
  10 { $values { "url" url } { "url'" url } }
  11 { $description "Adjusts a link URL by filtering the URL's query parameters through the " { $link modify-query } " generic word on every responder involved in handling the current request." } ;
  12
  13 HELP: client-state
  14 { $values { "key" string } { "value/f" { $maybe string } } }
  15 { $description "Looks up a cookie (if the current request is a GET or HEAD request) or a POST parameter (if the current request is a POST request)." }
  16 { $notes "This word is used by session management, conversation scope and asides." } ;
  17
  18 HELP: each-responder
  19 { $values { "quot" { $quotation ( ... responder -- ... ) } } }
  20 { $description "Applies the quotation to each responder involved in processing the current request." } ;
  21
  22 HELP: hidden-form-field
  23 { $values { "value" string } { "name" string } { "xml" "an XML chunk" } }
  24 { $description "Renders an HTML hidden form field tag as XML." }
  25 { $notes "This word is used by session management, conversation scope and asides." }
  26 { $examples
  27     { $example
  28         "USING: furnace.utilities io xml.writer ;"
  29         "\"bar\" \"foo\" hidden-form-field write-xml nl"
  30         "<input type=\"hidden\" value=\"bar\" name=\"foo\"/>"
  31     }
  32 } ;
  33
  34 HELP: link-attr
  35 { $values { "tag" tag } { "responder" "a responder" } }
  36 { $contract "Modifies an XHTML " { $snippet "a" } " tag." }
  37 { $notes "This word is called by " { $link "html.templates.chloe.tags.form" } "." }
  38 { $examples "Conversation scope adds attributes to link tags." } ;
  39
  40 HELP: modify-form
  41 { $values { "responder" "a responder" } { "xml/f" "an XML chunk or f" } }
  42 { $contract "Emits hidden form fields using " { $link hidden-form-field } "." }
  43 { $notes "This word is called by " { $link "html.templates.chloe.tags.form" } "." }
  44 { $examples "Session management, conversation scope and asides use hidden form fields to pass state." } ;
  45
  46 HELP: modify-query
  47 { $values { "query" assoc } { "responder" "a responder" } { "query'" assoc } }
  48 { $contract "Modifies the query parameters of a URL destined to be displayed as a link." }
  49 { $notes "This word is called by " { $link "html.templates.chloe.tags.form" } "." }
  50 { $examples "Asides add query parameters to URLs." } ;
  51
  52 HELP: modify-redirect-query
  53 { $values { "query" assoc } { "responder" "a responder" } { "query'" assoc } }
  54 { $contract "Modifies the query parameters of a URL destined to be used with a redirect." }
  55 { $notes "This word is called by " { $link "furnace.redirection" } "." }
  56 { $examples "Conversation scope and asides add query parameters to redirect URLs." } ;
  57
  58 HELP: nested-responders
  59 { $values { "seq" "a sequence of responders" } }
  60 { $description "Outputs a sequence of responders which participated in the processing of the current request, with the main responder first and the innermost responder last." } ;
  61
  62 HELP: referrer
  63 { $values { "referrer/f" { $maybe string } } }
  64 { $description "Outputs the current request's referrer URL." } ;
  65
  66 HELP: resolve-base-path
  67 { $values { "string" string } { "string'" string } }
  68 { $description "Resolves a responder-relative URL." } ;
  69
  70 HELP: resolve-template-path
  71 { $values { "pair" "a pair with shape " { $snippet "{ class string }" } } { "path" "a pathname string" } }
  72 { $description "Resolves a responder-relative template path." } ;
  73
  74 HELP: same-host?
  75 { $values { "url" url } { "?" "a boolean" } }
  76 { $description "Tests if the given URL is located on the same host as the URL of the current request." } ;
  77
  78 HELP: user-agent
  79 { $values { "user-agent" { $maybe string } } }
  80 { $description "Outputs the user agent reported by the client for the current request." } ;
  81
  82 HELP: vocab-path
  83 { $values { "vocab" "a vocabulary specifier" } { "path" "a pathname string" } }
  84 { $description "Outputs the full pathname of the vocabulary's source directory." } ;
  85
  86 HELP: exit-with
  87 { $values { "value" object } }
  88 { $description "Exits from an outer " { $link with-exit-continuation } "." } ;
  89
  90 HELP: with-exit-continuation
  91 { $values { "quot" { $quotation ( -- value ) } } { "value" "a value returned by the quotation or an " { $link exit-with } " invocation" } }
  92 { $description "Runs a quotation with the " { $link exit-continuation } " variable bound. Calling " { $link exit-with } " in the quotation will immediately return." }
  93 { $notes "Furnace actions and authentication realms wrap their execution in this combinator, allowing form validation failures and login requests, respectively, to immediately return an HTTP response to the client without running any more responder code." } ;
  94
  95 ARTICLE: "furnace.extension-points" "Furnace extension points"
  96 "Furnace features such as session management, conversation scope and asides need to modify URLs in links and redirects, and insert hidden form fields, to implement state on top of the stateless HTTP protocol. In order to decouple the server-side state management code from the HTML templating code, a series of hooks are used."
  97 $nl
  98 "Responders can implement methods on the following generic words:"
  99 { $subsections
 100     modify-query
 101     modify-redirect-query
 102     link-attr
 103     modify-form
 104 }
 105 "Presentation-level code can call the following words:"
 106 { $subsections
 107     adjust-url
 108     adjust-redirect-url
 109 } ;
 110
 111 ARTICLE: "furnace.misc" "Miscellaneous Furnace features"
 112 "Inspecting the chain of responders handling the current request:"
 113 { $subsections
 114     nested-responders
 115     each-responder
 116     resolve-base-path
 117 }
 118 "Vocabulary root-relative resources:"
 119 { $subsections
 120     vocab-path
 121     resolve-template-path
 122 }
 123 "Early return from a responder:"
 124 { $subsections
 125     with-exit-continuation
 126     exit-with
 127 }
 128 "Other useful words:"
 129 { $subsections
 130     hidden-form-field
 131     client-state
 132     user-agent
 133 } ;