basis/http/server/rewrite/rewrite-docs.factor

   1 IN: http.server.rewrite
   2 USING: help.syntax help.markup http.server ;
   3
   4 HELP: rewrite
   5 { $class-description "The class of directory rewrite responders. The slots are as follows:"
   6 { $list
   7   { { $slot "default" } " - the responder to call if no file name is provided." }
   8   { { $slot "child" } " - the responder to call if a file name is provided." }
   9   { { $slot "param" } " - the name of a request parameter which will store the first path component of the file name passed to the responder." }
  10 } } ;
  11
  12 HELP: <rewrite>
  13 { $values { "rewrite" rewrite } }
  14 { $description "Creates a new " { $link rewrite } " responder." }
  15 { $examples
  16   { $code
  17     "<rewrite>"
  18     "    <display-post-action> >>default"
  19     "    <display-comment-action> >>child"
  20     "    \"comment_id\" >>param"
  21   }
  22 } ;
  23
  24 HELP: vhost-rewrite
  25 { $class-description "The class of virtual host rewrite responders. The slots are as follows:"
  26 { $list
  27   { { $slot "default" } " - the responder to call if no host name prefix is provided." }
  28   { { $slot "child" } " - the responder to call if a host name prefix is provided." }
  29   { { $slot "param" } " - the name of a request parameter which will store the first host name component of the host name passed to the responder." }
  30   { { $slot "suffix" } " - the domain name suffix which will be chopped off the end of the request's host name in order to produce the parameter." }
  31 } } ;
  32
  33 HELP: <vhost-rewrite>
  34 { $values { "vhost-rewrite" vhost-rewrite } }
  35 { $description "Creates a new " { $link vhost-rewrite } " responder." }
  36 { $examples
  37   { $code
  38     "<vhost-rewrite>"
  39     "    <show-blogs-action> >>default"
  40     "    <display-blog-action> >>child"
  41     "    \"blog_id\" >>param"
  42     "    \"blogs.vegan.net\" >>suffix"
  43   }
  44 } ;
  45
  46 ARTICLE: "http.server.rewrite.overview" "Rewrite responder overview"
  47 "Rewrite responders take the file name and turn it into a request parameter named by the " { $slot "param" } " slot before delegating to a child responder. If a file name is provided, it calls the responder in the " { $slot "child" } " slot. If no file name is provided, they call the default responder in the " { $slot "default" } " slot."
  48 $nl
  49 "For example, suppose you want to have the following website schema:"
  50 { $list
  51 { { $snippet "/posts/" } " - show a list of posts" }
  52 { { $snippet "/posts/factor_language" } " - show thread with ID " { $snippet "factor_language" } }
  53 { { $snippet "/posts/factor_language/1" } " - show first comment in the thread with ID " { $snippet "factor_language" } }
  54 { { $snippet "/animals" } ", ... - a bunch of other actions" } }
  55 "One way to achieve this would be to have a nesting of responders as follows:"
  56 { $list
  57 { "A dispatcher at the top level" }
  58   { "A " { $link rewrite } " as a child of the dispatcher under the name " { $snippet "posts" } ". The rewrite has the " { $slot "param" } " slot set to, say, " { $snippet "post_id" } ". The " { $slot "default" } " slot is set to a Furnace action which displays a list of posts." }
  59   { "The child slot is set to a second " { $link rewrite } " instance, with " { $snippet "param" } " set to " { $snippet "comment_id" } ", the " { $slot "default" } " slot set to an action which displays a post identified by the " { $snippet "post_id" } " parameter, and the " { $snippet "child" } " slot set to an action which displays the comment identified by the " { $snippet "comment_id" } " parameter." } }
  60 "Note that parameters can be extracted from the request using the " { $link param } " word, but most of the time you want to use " { $vocab-link "furnace.actions" } " instead." ;
  61
  62 ARTICLE: "http.server.rewrite" "URL rewrite responders"
  63 "The " { $vocab-link "http.server.rewrite" } " vocabulary defines two responder types which can help make website URLs more human-friendly."
  64 { $subsections "http.server.rewrite.overview" }
  65 "Directory rewrite responders:"
  66 { $subsections
  67     rewrite
  68     <rewrite>
  69 }
  70 "Virtual host rewrite responders -- these chop off the value in the " { $snippet "suffix" } " slot from the tail of the host name, and use the rest as the parameter value:"
  71 { $subsections
  72     vhost-rewrite
  73     <vhost-rewrite>
  74 } ;
  75
  76 ABOUT: "http.server.rewrite"