Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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