Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 196 lines (133 sloc) 6.851 kb
1b168ac @kishorenc Stray log statements! Docs.
authored
1 #Road - route helper for Express
7f9cf36 Initial commit.
Kishore N C authored
2
3cc0712 @kishorenc Added support for specifying a callback that road will call after view i...
authored
3 A route helper for express that allows you to map routes, controllers and views by following logical conventions. See example application for use cases. You need express 2.x and ejs available to run the example.
7f9cf36 Initial commit.
Kishore N C authored
4
cff07e3 @kishorenc Published to NPM, made changes to examples, more documentation.
authored
5 ##Installation
ad90ecf @kishorenc First commit + added example app which uses road.
authored
6
cff07e3 @kishorenc Published to NPM, made changes to examples, more documentation.
authored
7 npm install road
7f9cf36 Initial commit.
Kishore N C authored
8
cff07e3 @kishorenc Published to NPM, made changes to examples, more documentation.
authored
9 ##Features
10
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
11 * Wire your routes to individual controllers and views using convention
85e42c2 @kishorenc Added acceptance tests.
authored
12 * Define custom routes which map custom URLs to specific controller methods
cff07e3 @kishorenc Published to NPM, made changes to examples, more documentation.
authored
13 * Serve the views in custom MIME types
85e42c2 @kishorenc Added acceptance tests.
authored
14 * View helper for serving JavaScript objects as application/json
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
15
9b1e047 @kishorenc minor bug fix, tested & verified on node 0.6.x
authored
16 ##Comptability
17
18 * Works on both node 0.4.x and 0.6.x
19 * Tested with Express 2.5.x
20
cff07e3 @kishorenc Published to NPM, made changes to examples, more documentation.
authored
21 See example application for complete use cases.
22
5e61b27 @kishorenc Update docs
authored
23 ##Quick Start
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
24
5e61b27 @kishorenc Update docs
authored
25 Integrating Road with your Express application is really simple. Tell Express to let Road handle the routing this way:
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
26
4abdb32 @kishorenc Update docs
authored
27 ``` javascript
28 var road = require('road');
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
29
4abdb32 @kishorenc Update docs
authored
30 // mount application routes using road
31 app.use(express.router(road));
32 ```
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
33
34 Road, by convention, expects you to drop your controllers into the `controllers` folder in your application root.
35
36 /controllers
37 /indexController.js
38 /eventsController.js
39
4abdb32 @kishorenc Update docs
authored
40 You can export your controller functions which automatically get mapped by road, again using convention. Every controller function needs to be prefixed with the HTTP method it's handling. For example, functions serving GET requests, need to be prefixed with `get_`, like this:
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
41
4abdb32 @kishorenc Update docs
authored
42 ``` javascript
43 // eventsController.js
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
44
4abdb32 @kishorenc Update docs
authored
45 // maps to: GET events/index or, just GET events/
46 this.get_index = function(req, res, callback) {
47 /* ... */
48 }
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
49
4abdb32 @kishorenc Update docs
authored
50 // maps to: GET events/foo/ or, GET events/:id/foo
51 this.get_foo = function(req, res, callback) {
52 /* ... */
53 }
54 ```
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
55
5e61b27 @kishorenc Update docs
authored
56 For handling a POST request, use `post_` prefix:
57
4abdb32 @kishorenc Update docs
authored
58 ``` javascript
59 // handles POST events/bar
60 this.post_bar = function(req, res, callback) {
61 /* ... */
62 }
63 ```
64
65 Instead of using res.render() to render your views, you can use the controller function's `callback`, which provides you with useful shortcuts:
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
66
4abdb32 @kishorenc Update docs
authored
67 ``` javascript
68 // serves the view file dynamic.ejs, along with the view data
69 this.get_dynamicView = function(req, res, callback) {
70 callback(null, 'dynamic', {name: "Road.js"});
71 }
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
72
4abdb32 @kishorenc Update docs
authored
73 // serves a view with custom MIME type (default is text/html)
74 this.get_dynamicViewAsPlainText = function(req, res, callback) {
75 callback(null, 'dynamic', {name:'Road.js'}, 'text/plain');
76 }
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
77
4abdb32 @kishorenc Update docs
authored
78 // serving plain text directly (no template)
79 this.get_plainText = function(req, res, callback) {
80 callback(null, {'text/plain': 'Plain text served as text/plain'});
81 }
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
82
4abdb32 @kishorenc Update docs
authored
83 // serving a JSON response (served as application/json)
84 this.get_jsonResponse = function(req, res, callback) {
85 var obj = {'foo': 'bar'};
86 callback(null, {'json': obj});
87 }
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
88
4abdb32 @kishorenc Update docs
authored
89 // for more use cases, see the example app
1ef964c @kishorenc Easy way to serve JSON response
authored
90
4abdb32 @kishorenc Update docs
authored
91 ```
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
92
4abdb32 @kishorenc Update docs
authored
93 ##View files
94
95 Place your view files in `/views` directory in your application's root. Each controller gets its own sub-directory inside `views`. For example, if you have a `show` method in your `fooController.js`, accessing `foo/show` will make Road look for the template file `views/foo/show.ejs`.
4a008d3 @kishorenc Added a few lines about convention used for locating views.
authored
96
97 /controllers
98 /fooController.js
99
100 /views
101 /foo
102 /show.ejs
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
103
4abdb32 @kishorenc Update docs
authored
104 ##Configuration options
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
105
4abdb32 @kishorenc Update docs
authored
106 **road.configure([options])**
5e61b27 @kishorenc Update docs
authored
107
4abdb32 @kishorenc Update docs
authored
108 The following properties can be set on the `options` object:
5e61b27 @kishorenc Update docs
authored
109
4abdb32 @kishorenc Update docs
authored
110 * `viewEngine`: view engine to be used for rendering the views (e.g. ejs, jade). Default: `ejs`
111 * `routes`: array with custom routing rules (see the following section on routing rules for more details)
112 * `useLayout`: specifies whether Express should use a layout while rendering the view
113 * `callback`: this callback will be fired when Road is done with its job
5e61b27 @kishorenc Update docs
authored
114
4abdb32 @kishorenc Update docs
authored
115 ##View helpers
a49f5a6 @kishorenc Added more documentation to README, minor change to example (showcase us...
authored
116
4abdb32 @kishorenc Update docs
authored
117 As shown in the examples above, Road provides a wrapper over `res.render` and allows you to render your views by using the `callback` argument passed to your controller method. However, you can simply stick to `res.render` as well for rendering your views. Road uses `ejs` as the default view engine. To specify another view engine, e.g. jade, you can do so via the `viewEngine` configuration property.
cff07e3 @kishorenc Published to NPM, made changes to examples, more documentation.
authored
118
4abdb32 @kishorenc Update docs
authored
119 ``` javascript
120 road.configure({viewEngine: 'jade'});
121 ```
5e61b27 @kishorenc Update docs
authored
122
4abdb32 @kishorenc Update docs
authored
123 ##Routing rules
5e61b27 @kishorenc Update docs
authored
124
4abdb32 @kishorenc Update docs
authored
125 Road supports the following routing rule by default:
5e61b27 @kishorenc Update docs
authored
126
4abdb32 @kishorenc Update docs
authored
127 /:controller?/:id?/:action? (for all HTTP verbs)
3cc0712 @kishorenc Added support for specifying a callback that road will call after view i...
authored
128
4abdb32 @kishorenc Update docs
authored
129 To define custom routes, place a route file in your application's root. Any routing rule defined in `routes.js` will take precedence over the default routing rules above.
a148bc2 @kishorenc status set on err object to indicate type of error. fixed issues raised ...
authored
130
4abdb32 @kishorenc Update docs
authored
131 ``` javascript
132 // routes.js (place this in your application root)
133 module.exports = [
134
135 // routes `/path/to/foo` to `get_show()` method of `fooController`
136 ['map', 'get', '/path/to/foo/:id', 'foo', 'show'],
5e61b27 @kishorenc Update docs
authored
137
4abdb32 @kishorenc Update docs
authored
138 ];
139 ```
140
141 When you configure Road, you pass these routes using the `routes` property of the configuration options this way:
142
143 ``` javascript
144 road.configure({routes: require('./routes')});
145 ```
146
147 ##Registering a callback
148
149 Finally, if you want to register a callback for Road to call when it's done rendering the view (or encounters an error), you can do so like this:
5e61b27 @kishorenc Update docs
authored
150
4abdb32 @kishorenc Update docs
authored
151 ``` javascript
152 function roadCallback(err, req, res, next) {
153 if(err) return next(err);
154 // else, do something ...
155 }
156 road.configure({callback: roadCallback});
157 ```
5e61b27 @kishorenc Update docs
authored
158
4abdb32 @kishorenc Update docs
authored
159 Road sets a `status` property on the callback's `err` argument to indicate the type of error. This can be used for rendering an appropriate view with the correct HTTP status code. For missing controller or controller methods, `err.status` is set to 404 (to indicate a missing resource), while any other error passed to Road from a controller method is set to 500. If the error object already has a status set, Road does not override that.
5e61b27 @kishorenc Update docs
authored
160
85e42c2 @kishorenc Added acceptance tests.
authored
161 ##Running the tests
e3bcc38 @kishorenc Note about todo.
authored
162
4abdb32 @kishorenc Update docs
authored
163 To run the tests, first install the dev dependencies (ejs, mocha and request):
e3bcc38 @kishorenc Note about todo.
authored
164
85e42c2 @kishorenc Added acceptance tests.
authored
165 $ npm install
166 $ npm install -g mocha
167
168 Run the tests from the test folder this way:
169
170 $ mocha test.js
7f9cf36 Initial commit.
Kishore N C authored
171
172 ##License
173
174 (The MIT License)
175
ad90ecf @kishorenc First commit + added example app which uses road.
authored
176 Copyright (c) 2011 Kishore Nallan <kishore@kishorelive.com>
7f9cf36 Initial commit.
Kishore N C authored
177
178 Permission is hereby granted, free of charge, to any person obtaining
179 a copy of this software and associated documentation files (the
180 'Software'), to deal in the Software without restriction, including
181 without limitation the rights to use, copy, modify, merge, publish,
182 distribute, sublicense, and/or sell copies of the Software, and to
183 permit persons to whom the Software is furnished to do so, subject to
184 the following conditions:
185
186 The above copyright notice and this permission notice shall be
187 included in all copies or substantial portions of the Software.
188
189 THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
190 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
191 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
192 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
193 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
194 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
195 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.