Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 205 lines (147 sloc) 3.866 kb
38958d8 @kieran fixed where array bug, added docs for conditions
authored
1 Barista is a simple URL router for NodeJS.
a577b0b @kieran Initial commit
authored
2
3 Getting Barista
4 ===============
5
6 Install via npm, thusly:
7
8 ```javascript
9 npm install barista
10 ```
11
12 Using Barista
13 -------------
14
15 ```javascript
16 var Router = require('barista').Router;
17
18 var router = new Router;
19 ```
20
38958d8 @kieran fixed where array bug, added docs for conditions
authored
21 Adding routes
22 -------------
a577b0b @kieran Initial commit
authored
23
38958d8 @kieran fixed where array bug, added docs for conditions
authored
24 ### A simple example
87f2fb5 @kieran trying to figure out GitHub Markdown...
authored
25
a577b0b @kieran Initial commit
authored
26 ```javascript
27 router.match( '/products', 'GET' )
28 .to( 'products.index' )
38958d8 @kieran fixed where array bug, added docs for conditions
authored
29 ```
a577b0b @kieran Initial commit
authored
30
38958d8 @kieran fixed where array bug, added docs for conditions
authored
31 ### Rails-esque variable names
32
33 ```javascript
a577b0b @kieran Initial commit
authored
34 router.match( '/products/:id', 'GET' )
35 .to( 'products.show' )
36
38958d8 @kieran fixed where array bug, added docs for conditions
authored
37 router.match( '/profiles/:username', 'GET' )
38 .to( 'users.show' )
39
a577b0b @kieran Initial commit
authored
40 router.match( '/products/:id(.:format)', 'GET' )
41 .to( 'products.show' )
38958d8 @kieran fixed where array bug, added docs for conditions
authored
42 ```
43
44 ### Match conditions
a577b0b @kieran Initial commit
authored
45
38958d8 @kieran fixed where array bug, added docs for conditions
authored
46 ```javascript
47 router.match( '/:beverage/near/:zipcode', 'GET' )
48 .to( 'beverage.byZipCode' )
49 .where({
50 // an array of options
51 beverage: [ 'coffee', 'tea', 'beer', 'warm_sake' ],
52 // a regex pattern
53 zipcode: /^\d{5}(-\d{4})?$/
54 })
55
56 router.match( '/:beverage/near/:location', 'GET' )
57 .to( 'beverage.byLocation' )
58 .where({
59 // could be a postal code
60 // OR a zip code
61 // OR the word 'me' (geolocation FTW)
62 location: [ /^\d{5}(-\d{4})?$/, /^[ABCEGHJKLMNPRSTVXY]{1}\d{1}[A-Z]{1} *\d{1}[A-Z]{1}\d{1}$/, 'me' ]
63 })
64 ```
65
66 ### Convenience methods
67
68 ```javascript
a577b0b @kieran Initial commit
authored
69 router.get( '/products/:id(.:format)' )
70 .to( 'products.show' )
71
72 router.put( '/products/:id(.:format)' )
73 .to( 'products.update' )
74
75 router.post( '/products' )
76 .to( 'products.create' )
77
78 router.delete( '/products' )
79 .to( 'products.destroy' )
80 ```
87f2fb5 @kieran trying to figure out GitHub Markdown...
authored
81
a577b0b @kieran Initial commit
authored
82 ### REST Resources
83
84 ```javascript
85 router.resource( 'products' )
86 ```
87
88 is equivalent to:
89
90 ```javascript
91 router.get( '/products(.:format)' )
92 .to( 'products.index' )
93
94 router.get( '/products/add(.:format)' )
95 .to( 'products.add' )
96
97 router.get( '/products/:id(.:format)' )
98 .to('products.show' )
99
100 router.get('/products/:id/edit(.:format)' )
101 .to( 'products.edit' )
102
103 router.post('/products(.:format)' )
104 .to( 'products.create' )
105
106 router.put('/products/:id(.:format)' )
107 .to( 'products.update' )
108
109 router.delete('/products/:id(.:format)' )
110 .to( 'products.destroy' )
111 ```
112
113 Resolution & dispatching
114 ------------------------
115
87f2fb5 @kieran trying to figure out GitHub Markdown...
authored
116 The `router.first( url, method [, callback] )` method can be used in two ways:
a577b0b @kieran Initial commit
authored
117
118 ```javascript
119 var params = router.first( '/products/15', 'GET' )
120 ```
87f2fb5 @kieran trying to figure out GitHub Markdown...
authored
121
a577b0b @kieran Initial commit
authored
122 OR
87f2fb5 @kieran trying to figure out GitHub Markdown...
authored
123
a577b0b @kieran Initial commit
authored
124 ```javascript
125 router.first( '/products/15', 'GET', function( params ){
126 // dispatch the request or something
127 })
128 ```
129
130 You can get all the matching routes like so:
87f2fb5 @kieran trying to figure out GitHub Markdown...
authored
131
a577b0b @kieran Initial commit
authored
132 ```javascript
133 var params = router.all( '/products/15', 'GET' )
134
135 //=> [params, params, params....]
136 ```
137
138 Route generation
139 ----------------
140
141 Pass in a params hash, get back a tasty string:
87f2fb5 @kieran trying to figure out GitHub Markdown...
authored
142
a577b0b @kieran Initial commit
authored
143 ```javascript
3b1b843 @kieran Hatin' on trailing whitespace
authored
144 router.url( {
145 controller: 'products',
146 action: 'show',
a577b0b @kieran Initial commit
authored
147 id: 5
148 } )
149 //=> '/products/5'
150
151 router.url( {
3b1b843 @kieran Hatin' on trailing whitespace
authored
152 controller: 'products',
153 action: 'show',
154 id: 5,
a577b0b @kieran Initial commit
authored
155 format: 'json'
156 } )
157 //=> '/products/5.json'
158 ```
87f2fb5 @kieran trying to figure out GitHub Markdown...
authored
159
a577b0b @kieran Initial commit
authored
160 Set the optional second parameter to `true` if you want
161 extra params appended as a query string:
87f2fb5 @kieran trying to figure out GitHub Markdown...
authored
162
a577b0b @kieran Initial commit
authored
163 ```javascript
3b1b843 @kieran Hatin' on trailing whitespace
authored
164 router.url({
165 controller: 'products',
166 action: 'show',
167 id: 5,
168 format: 'json',
169 love: 'cheese'
a577b0b @kieran Initial commit
authored
170 }, true )
171 //=> '/products/5.json?love=cheese'
172 ```
173
c4620f5 @kieran added caveats, version bump
authored
174
175 Caveats & TODOs
176 ---------------
177 nested optional segments are currently unsupported. e.g. this won't work:
178
179 ```javascript
180 router.get( '/:controller(/:action(/:id(.:format)))' )
181 ```
182
183 nesting routes & resources is also still on the TODO list
184
185
a577b0b @kieran Initial commit
authored
186 Things I forgot...
187 ------------------
188 ...might be in the `/docs` folder...
189
190 ...or might not exist at all.
191
192
193 It's broken!
194 ------------
195 Shit happens.
196
197 Write a test that fails and add it to the tests folder,
198 then create an issue!
199
200 Patches welcome :-)
201
202
203 Who are you?
204 ------------
205 I'm [Kieran Huggins](mailto:kieran@refactory.ca), partner at [Refactory](http://refactory.ca) in Toronto, Canada.
Something went wrong with that request. Please try again.