Docs Developer Site
Router library
arrow-down
DeveloperDocsRouter LibraryStable

Router Library

Contents

xp 7.+ blue

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) {
  ...
});
3.+ blue

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.
3.+ blue

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) {
  ...
});

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.

Contents

Contents