Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 155 lines (129 sloc) 3.976 kb
61aea3a Caolan McMahon added code so far
authored
1 # Dispatch
2
3 A really simple URL dispatcher for
ec1db92 Caolan McMahon add support for non-connect http servers
authored
4 [Connect](http://github.com/senchalabs/connect) or a plain Node.js HTTP Server.
5 Allows arbitrarily nested regular expressions for matching URLs and calling an
6 associated function.
7
8 ```js
9 var Connect = require('connect'),
10 dispatch = require('dispatch');
11
12 Connect.createServer(
13 dispatch({
14 '/about': function(req, res, next){
15 ...
16 },
17 '/user/:id': function(req, res, next, id){
18 ...
19 },
20 '/user/posts': function(req, res, next){
21 ...
22 },
23 '/user/posts/(\\w+)': function(req, res, next, post){
24 ...
25 }
26 })
27 );
28 ```
29
30 Or, using a vanilla HTTP Server:
31
32 ```js
33 var http = require('http');
34
35 var server = http.createServer(
36 dispatch({
37 '/about': function(req, res){
38 ...
39 },
40 '/user/:id': function(req, res, id){
41 ...
42 }
43 })
44 );
45
46 server.listen(8080);
47 ```
61aea3a Caolan McMahon added code so far
authored
48
49 Dispatch can be used with a straight-forward object literal containing view
50 functions keyed by URL. As you can see from the last URL in the list, captured
51 groups are passed to the matching function as an argument.
52
4883cd3 Caolan McMahon add named params
authored
53 You can also use :named parameters in a URL, which is just a more readable way
54 of capturing ([^\/]+). Named parameters are passed to the matched function in
55 the same way as normal regular expression groups.
56
61aea3a Caolan McMahon added code so far
authored
57 So far so predictable. However, it is also possible to nest these objects as
58 you see fit:
59
ec1db92 Caolan McMahon add support for non-connect http servers
authored
60 ```js
61 Connect.createServer(
62 dispatch({
63 '/about': function(req, res, next){ ... },
64 '/user': {
65 '/': function(req, res, next){ ... },
66 '/posts': function(req, res, next){ ... },
67 '/posts/(\\w+)': function(req, res, next, post){ ... }
68 }
69 })
70 );
71 ```
61aea3a Caolan McMahon added code so far
authored
72
73 This helps you tidy up the structure to make it more readable. It also makes
74 renaming higher-level parts of the path much simpler. If we wanted to change
75 'user' to 'member', we'd now only have to do that once. Another advantage of
76 being able to nest groups of URLs is mounting reusable apps in your site tree.
77 Let's assume that 'user' is actually provided by another module:
78
ec1db92 Caolan McMahon add support for non-connect http servers
authored
79 ```js
80 Connect.createServer(
81 dispatch({
82 '/about': function(req, res, next){ ... },
83 '/user': require('./user').urls
84 })
85 );
86 ```
61aea3a Caolan McMahon added code so far
authored
87
88 Easy! A really lightweight and flexible URL dispatcher that just does the
3747bdf Caolan McMahon add method match to url definitions
authored
89 obvious.
90
91 Its also possible to define methods for URLs:
92
ec1db92 Caolan McMahon add support for non-connect http servers
authored
93 ```js
94 Connect.createServer(
95 dispatch({
96 '/user': {
97 'GET /item': function(req, res, next){ ... },
98 'POST /item': function(req, res, next){ ... },
99 }
100 })
101 );
102 ```
3747bdf Caolan McMahon add method match to url definitions
authored
103
104 Just prefix the URL with the http method in uppercase followed by whitespace
105 and then the path you want to match against. Nested URLs always match the last
83d2df5 Caolan McMahon allow a method without a path following it
authored
106 method defined in the tree. Because of this, you can use the following style for
107 matching request methods, if you prefer:
108
ec1db92 Caolan McMahon add support for non-connect http servers
authored
109 ```js
110 dispatch({
111 '/test': {
112 GET: function (req, res, next) {
113 ...
114 },
115 POST: function (req, res, next) {
116 ...
83d2df5 Caolan McMahon allow a method without a path following it
authored
117 }
ec1db92 Caolan McMahon add support for non-connect http servers
authored
118 }
119 })
120 ```
61aea3a Caolan McMahon added code so far
authored
121
122 A couple of implementation points:
123
124 1. The regular expressions automatically have '^' and '$' added to the pattern
125 at the start and end or the URL.
126 2. Only the first match is called, subsequent matches for a URL will not be
127 called.
128 3. If there are no matches, the request is passed to the next handler in the
129 Connect middleware chain.
130
131 I like to combine this with [quip](http://github.com/caolan/quip) for rapid
132 prototyping and just getting my ideas down in code:
133
ec1db92 Caolan McMahon add support for non-connect http servers
authored
134 ```js
135 var Connect = require('connect'),
136 quip = require('quip'),
137 dispatch = require('dispatch');
138
139 var server = Connect.createServer(
140 quip(),
141 dispatch({
142 '/': function(req, res, next){
143 res.text('hello world!');
144 },
145 '/api': function(req, res, next){
146 res.json({hello: 'world'});
147 }
148 })
149 );
150
151 server.listen(8080);
152 ```
61aea3a Caolan McMahon added code so far
authored
153
154 Have fun!
Something went wrong with that request. Please try again.