Routing
- Basic Routing
- Route Parameters
- Route Filters
- Named Routes
- Route Groups
- Sub-Domain Routing
- Route Prefixing
- Route Model Binding
- Throwing 404 Errors
- Routing To Controllers
Basic Routing
Most of the routes for your application will be defined in the app/routes.js
file. The simplest Quorra routes
consist of a URI and a Closure callback.
Accessing application router instance
var Route = App.router;
Basic GET Route
Route.get('/', function(req, res)
{
res.writeHead(200, {'Content-Type': 'text/plain'});
res.end('Hello World');
});
Basic POST Route
Route.post('foo/bar', function(req, res)
{
res.writeHead(200, {'Content-Type': 'text/plain'});
res.end('Hello World');
});
Registering A Route For Multiple Verbs
Route.match(['GET', 'POST'], '/', function(req, res)
{
res.writeHead(200, {'Content-Type': 'text/plain'});
res.end('Hello World');
});
Registering A Route Responding To Any HTTP Verb
Route.any('foo', function(req, res)
{
res.writeHead(200, {'Content-Type': 'text/plain'});
res.end('Hello World');
});
Forcing A Route To Be Served Over HTTPS
Route.get('foo', {'https': true, uses: function(req, res)
{
res.writeHead(200, {'Content-Type': 'text/plain'});
res.end('Must be over HTTPS');
}});
Often, you will need to generate URLs to your routes, you may do so using the URL.to method:
var URL = App.url;
var url = URL.to('foo');
Route Parameters
Route.get('user/{id}', function(req, res, id)
{
res.writeHead(200, {'Content-Type': 'text/plain'});
res.end('User '+id);
});
Optional Route Parameters
Route.get('user/{name?}', function(req, res, name)
{
if(name === undefined) {
name = 'no name';
}
res.writeHead(200, {'Content-Type': 'text/plain'});
res.end(name);
});
Regular Expression Route Constraints
Route.get('user/{name}', function(req, res, name)
{
//
})
.where('name', '[A-Za-z]+');
Route.get('user/{id}', function(req, res, id)
{
//
})
.where('id', '[0-9]+');
Passing An Object Of Wheres
Of course, you may pass an object of constraints when necessary:
Route.get('user/{id}/{name}', function(req, res, id, name)
{
//
})
.where({'id': '[0-9]+', 'name': '[a-z]+'});
Defining Global Patterns
If you would like a route parameter to always be constrained by a given regular expression, you may use the pattern method:
Route.pattern('id', '[0-9]+');
Route.get('user/{id}', function(req, res, id)
{
// Only called if {id} is numeric.
});
Accessing A Route Parameter Value
If you need to access a route parameter value outside of a route, you may use the req.routeParameter
method:
Route.filter('foo', function(req, res, next)
{
if (req.routeParameter('id') == 1)
{
//
}
});
Route Filters
Route filters provide a convenient way of limiting access to a given route, which is useful for creating areas of
your site which require authentication. You can register your application filters in the app/filters.js
file.
Defining A Route Filter
var URL = App.url;
Route.filter('old', function(req, res, next)
{
if (req.input.get('age') < 200)
{
res.redirect(URL.to('home'));
} else {
next();
}
});
Attaching A Filter To A Route
Route.get('user', {'before': 'old', uses: function(req, res)
{
res.writeHead(200, {'Content-Type': 'text/plain'});
res.end('You are over 200 years old!');
}});
Attaching A Filter To A Controller Action
Route.get('user', {'before': 'old', 'uses': '[email protected]'});
Attaching Multiple Filters To A Route
Route.get('user', {'before': 'auth|old', uses: function(req, res)
{
res.writeHead(200, {'Content-Type': 'text/plain'});
res.end('You are authenticated and over 200 years old!');
}});
Attaching Multiple Filters Via Array
Route.get('user', {'before': ['auth', 'old'], uses: function(req, res)
{
res.writeHead(200, {'Content-Type': 'text/plain'});
res.end('You are authenticated and over 200 years old!');
}});
Specifying Filter Parameters
Route.filter('age', function(req, res, next, value)
{
//
});
Route.get('user', {'before': 'age:200', uses: function(req, res)
{
res.writeHead(200, {'Content-Type': 'text/plain'});
res.end('Hello World');
}});
Pattern Based Filters
You may also specify that a filter applies to an entire set of routes based on their URI.
Route.filter('admin', function(req, res, next)
{
//
});
Route.when('admin/*', 'admin');
In the example above, the admin filter would be applied to all routes beginning with admin/
. The asterisk is used as
a wildcard, and will match any combination of characters.
You may also constrain pattern filters by HTTP verbs:
Route.when('admin/*', 'admin', ['post']);
Named Routes
Named routes make referring to routes when generating redirects or URLs more convenient. You may specify a name for a route like so:
Route.get('user/profile', {'as': 'profile', uses: function(req, res)
{
//
}});
You may also specify route names for controller actions:
Route.get('user/profile', {'as': 'profile', 'uses': '[email protected]'});
Now, you may use the route's name when generating URLs:
var URL = App.url;
var profileUrl = URL.route('profile');
Route Groups
Sometimes you may need to apply filters to a group of routes. Instead of specifying the filter on each route, you may use a route group:
Route.group({'before': 'auth'}, function()
{
Route.get('/', function(req, res)
{
// Has Auth Filter
});
Route.get('user/profile', function(req, res)
{
// Has Auth Filter
});
});
You may also use the namespace parameter within your group array to specify all controllers within that group as being in a given namespace:
Route.group({'namespace': 'controllers/admin'}, function()
{
//
});
Sub-Domain Routing
Quorra routes supports sub-domain routing. Quorra routes are also able to handle wildcard sub-domains, and will pass your wildcard parameters from the domain:
Registering Sub-Domain Routes
Route.get('users', {domain: 'users.myapp.com', 'uses': function(req, res) {
//
}});
Route.group({'domain': '{account}.myapp.com'}, function() {
Route.get('user/{id}', function(req, res, account, id) {
//
});
});
Route Prefixing
A group of routes may be prefixed by using the prefix option in the attributes object of a group:
Route.group({'prefix': 'admin'}, function()
{
Route.get('user', function()
{
//
});
});
Route Model Binding
Model binding provides a convenient way to inject model instances into your routes. For example, instead of injecting
a user's ID, you can inject the entire User model instance that matches the given ID. First, use the Route.model
method to specify the model that should be used for a given parameter:
Binding A Parameter To A Model
var Route = App.router;
Route.model('user', 'User');
Next, define a route that contains a {user}
parameter:
Route.get('profile/{user}', function(req, res, user)
{
//
});
Since we have bound the {user}
parameter to the User model, a User instance will be injected into the route. So, for
example, a request to profile/1
will inject the User instance which has an ID of 1.
Note: If a matching model instance is not found in the database, a 404 error will be thrown.
If you wish to specify your own "not found" behavior, you may pass a callback as the third argument to the model method:
Route.model('user', 'User', function(req, res, next)
{
throw new Error(404);
});
Sometimes you may wish to use your own resolver for route parameters. Simply use the Route::bind
method:
Route.bind('user', function(value, route, req, callback)
{
User.findOne(value, function(err, model){
callback(model);
});
});
Throwing 404 Errors
There are two ways to manually trigger a 404 error from a route. First, you may use the App.abort method:
req.abort(404);
Second, you may throw an instance of Error with status property equal to 404.
More information on handling 404 exceptions and using custom responses for these errors may be found in the errors section of the documentation.
Routing To Controllers
Quorra allows you to not only route to Closures, but also to controller classes.
See the documentation on Controllers for more details.