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

   1 ! Copyright (C) 2008 Your name.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: classes help.markup help.syntax io.streams.string
   4 multiline ;
   5 IN: http.server.dispatchers
   6
   7 HELP: new-dispatcher
   8 { $values { "class" class } { "dispatcher" dispatcher } }
   9 { $description "Creates a new instance of a subclass of " { $link dispatcher } "." } ;
  10
  11 HELP: dispatcher
  12 { $description "The class of dispatchers. May be subclassed, in which case subclasses should be constructed by calling " { $link new-dispatcher } "." } ;
  13
  14 HELP: <dispatcher>
  15 { $values { "dispatcher" dispatcher } }
  16 { $description "Creates a new pathname dispatcher." } ;
  17
  18 HELP: vhost-dispatcher
  19 { $description "The class of virtual host dispatchers." } ;
  20
  21 HELP: <vhost-dispatcher>
  22 { $values { "dispatcher" vhost-dispatcher } }
  23 { $description "Creates a new virtual host dispatcher." } ;
  24
  25 HELP: add-responder
  26 { $values
  27      { "dispatcher" dispatcher } { "responder" "a responder" } { "path" "a pathname string or hostname" } }
  28 { $description "Adds a responder to a dispatcher." }
  29 { $notes "The " { $snippet "path" } " parameter is interpreted differently depending on the dispatcher type." }
  30 { $side-effects "dispatcher" } ;
  31
  32 ARTICLE: "http.server.dispatchers.example" "HTTP dispatcher examples"
  33 { $heading "Simple pathname dispatcher" }
  34 { $code
  35     <" <dispatcher>
  36     <new-action> "new" add-responder
  37     <edit-action> "edit" add-responder
  38     <delete-action> "delete" add-responder
  39     <list-action> "" add-responder
  40 main-responder set-global">
  41 }
  42 "In the above example, visiting any URL other than " { $snippet "/new" } ", " { $snippet "/edit" } ", " { $snippet "/delete" } ", or " { $snippet "/" } " will result in a 404 error."
  43 { $heading "Another pathname dispatcher" }
  44 "On the other hand, suppose we wanted to route all unrecognized paths to a ``view'' action:"
  45 { $code
  46     <" <dispatcher>
  47     <new-action> "new" add-responder
  48     <edit-action> "edit" add-responder
  49     <delete-action> "delete" add-responder
  50     <view-action> >>default
  51 main-responder set-global">
  52 }
  53 "The " { $slot "default" } " slot holds a responder to which all unrecognized paths are sent to."
  54 { $heading "Dispatcher subclassing example" }
  55 { $code
  56     <" TUPLE: golf-courses < dispatcher ;
  57
  58 : <golf-courses> ( -- golf-courses )
  59     golf-courses new-dispatcher ;
  60
  61 <golf-courses>
  62     <new-action> "new" add-responder
  63     <edit-action> "edit" add-responder
  64     <delete-action> "delete" add-responder
  65     <list-action> "" add-responder
  66 main-responder set-global">
  67 }
  68 "The action templates can now emit links to responder-relative URLs prefixed by " { $snippet "$golf-courses/" } "."
  69 { $heading "Virtual hosting example" }
  70 { $code
  71     <" <vhost-dispatcher>
  72     <casino> "concatenative-casino.com" add-responder
  73     <dating> "raptor-dating.com" add-responder
  74 main-responder set-global">
  75 }
  76 "Note that the virtual host dispatcher strips off a " { $snippet "www." } " prefix, so " { $snippet "www.concatenative-casino.com" } " would be routed to the " { $snippet "<casino>" } " responder instead of receiving a 404." ;
  77
  78 ARTICLE: "http.server.dispatchers" "HTTP dispatchers and virtual hosting"
  79 "The " { $vocab-link "http.server.dispatchers" } " vocabulary implements two responders which route HTTP requests to one or more child responders."
  80 { $subsection "http.server.dispatchers.example" }
  81 "Pathname dispatchers implement a directory hierarchy where each subdirectory is its own responder:"
  82 { $subsection dispatcher }
  83 { $subsection <dispatcher> }
  84 "Virtual host dispatchers dispatch each virtual host to a different responder:"
  85 { $subsection vhost-dispatcher }
  86 { $subsection <vhost-dispatcher> }
  87 "Adding responders to dispatchers:"
  88 { $subsection add-responder }
  89 "The " { $slot "default" } " slot holds a responder which receives all unrecognized URLs. By default, it responds with 404 messages." ;
  90
  91 ABOUT: "http.server.dispatchers"