Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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