Router Library
Contents
This library implements a simple HTTP router. It should be used from an application’s webapp.js controller.
To start using this library, put the following into your build.gradle file:
dependencies {
include 'com.enonic.lib:lib-router:3.1.0'
}Usage
The first thing you will need to do is create a router object in your controller. You can create multiple routers if you want to, but here we will illustrate the use of one single router.
// Create a new router.
var router = require('/lib/router')();The next thing to do is dispatch all requests to the newly created router.
// Dispatch all requests to the router.
exports.all = function(req) {
return router.dispatch(req);
};Adding routes
You can add routes that match a method and a path. The path can also have placeholders (or path-parameters) as shown later. Let’s add some routes:
// Add a route for the GET method.
router.get('/persons', function(req) {
...
});
// Add a route for the POST method.
router.post('/persons', function(req) {
...
});To add routes with path-parameters, use the curly brackets {…} notation:
// Add a router for person.
router.get('/persons/{id}', function(req) {
// Get the path parameter named "id".
var id = req.pathParams.id;
...
});Or, if you want to restrict it to a regular expression:
router.get('/persons/{id:[0-9]+}', function(req) {
...
});To allow for matching all that starts with a path, you can use regular expressions for this too:
router.get('/match/everything/{path:.+}', function(req) {
...
});You can also match for all HTTP methods:
router.all('/persons', function(req) {
...
});
Match URL with and without trailing slash:
router.route('GET', '/persons/?', function(req) {
...
});| Before version 3.0.0 trailing slashes were always ignored. Starting from version 3.0.0 trailing slash should be explicitly specified in pattern. |
Specify multiple patterns for the same handler:
router.route('GET', ['/static', '/static/{path:.*}'], function(req) {
...
});Filters
Filters can be added to the routing. All filters are executed in the order that they were added. In each filter you can decide if you want to go to the next in the chain or just abort the execution chain.
// Add a filter to just log the request.
router.filter(function(req, next) {
// Log info.
log.info('Entered ' + req.path);
// Execute next and return.
return next(req);
});API
The following functions are defined in this library.
get
Adds a route that matches the GET method.
Parameters
-
pattern(string) Path pattern to match. -
handler(function) Handler to execute on match.
Example
router.get('/persons/{id}', function(req) {
...
});post
Adds a route that matches the POST method.
Parameters
-
pattern(string) Path pattern to match. -
handler(function) Handler to execute on match.
Example
router.post('/persons/{id}', function(req) {
...
});delete
Adds a route that matches the DELETE method.
Parameters
-
pattern(string) Path pattern to match. -
handler(function) Handler to execute on match.
Example
router.delete('/persons', function(req) {
...
});put
Adds a route that matches the PUT method.
Parameters
-
pattern(string) Path pattern to match. -
handler(function) Handler to execute on match.
Example
router.put('/persons', function(req) {
...
});head
Adds a route that matches the HEAD method.
Parameters
-
pattern(string) Path pattern to match. -
handler(function) Handler to execute on match.
Example
router.head('/persons/{id}', function(req) {
...
});all
Adds a route that matches all methods.
Parameters
-
pattern(string) Path pattern to match. -
handler(function) Handler to execute on match.
Example
router.all('/persons', function(req) {
...
});route
Adds a route to this router.
Parameters
-
method(string) Method to match. * for all. -
pattern(string) Path pattern to match. -
handler(function) Handler to execute on match.
Example
router.route('POST', '/persons', function(req) {
...
});filter
Adds a filter to this router.
Parameters
-
filter(function) Filter handler to execute.
Example
router.filter(function(req, next) {
...
});dispatch
Dispatch the request to this router.
Parameters
-
req(object) HTTP request.
Example
exports.all = function(req) {
return router.dispatch(req);
};Compatibility
This library requires Enonic XP release 7.0.0 or higher.
