Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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