xonecas.io
142
St

startsInvasion / files

startsInvasion / libs / node_modules / reqwest / build / dispatch / README.md

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