This package has been deprecated

Author message:

no longer maintained

Rhombus.js

Rhombus is a routing library for JavaScript. It works in modern browsers (IE 9 and later are supported) and other environments (e.g. node.js).

Rhombus allows you to do the reverse of route matching, to generate a string that would match a certain route with a given set of parameters. That way, you can avoid manually managing the strings that are used for routing.

What does it do?

Rhombus, like other application routers, maps strings to callback functions. These strings can also contain parameters that are then passed to the callback.

This can be used to map URLs to controllers/views, but is not limited to URLs. It could also be used to call functions depending on parts of strings like namespaced event names.

Installation

You can install as a node module with npm install rhombus.js or just download the minified file here.

Usage

//load via require.js:
var Rhombus = require('path/to/rhombus');

//or node.js style:
var Rhombus = require('rhombus');

//or just load the file with a script tag in a browser

//get a router instance:
var rh = new Rhombus();

//apply configuration
rh.setRoutes([
    {
        /* ... */
    },
    {
        /* ... */
    }
]);

Regular route matching

Here's an example route configuration for a simple blog application:

var rh = new Rhombus();
rh.setRoutes([
    {
        name: "home",
        pattern: "^/$",
        callback: function(r, next) {
            //handle the rendering of the home page
        }
    },
    {
        name: "blog",
        pattern: "^/blog$",
        callback: function(r, next) {
            //handle the rendering of the latest blog posts
        }
    }
]);

//to match a string against the routes:
rh.match("/blog");

//you can also pass some data to the router
rh.match("/blog", {foo: "bar"});

//this data will be passed to the callback as the first argument.

Routes in Rhombus are hierarchical. Any route can have child routes that are matched after the parent. So in the above example, adding a blog archive page with the URL /blog/archive would look like this:

[
    {
        name: "home",
        pattern: "^/$",
        callback: function(r, next) {
            //handle the rendering of the home page
        }
    },
    {
        name: "blog",
        pattern: "^/blog$",
        callback: function(r, next) {
            /*
             * here you could do stuff that is needed for all the pages in the "blog" section
             * of your application.
             *
             * The important thing is to call "next()" to continue routing to the child routes.
             */

            next();
        },
        routes: [
            {
                name: "latest",
                pattern: "^/$",
                callback: function(r, next) {
                    //handle the rendering of the latest blog posts
                }
            },
            {
                name: "archive",
                pattern: "^/archive$",
                callback: function(r, next) {
                    //handle the rendering of the archive page
                }
            }
        ]
    }
]

To embed parameters in the routed strings/URLs you can provide a placeholder with a RegExp pattern. Let's limit the blog archive to a single month:

{
    name: "archive",
    pattern: "^/archiv/:year=\\d{4}:/:month=\\d{2}:$",
    callback: function(r, next) {
        /*
         * for the URL "/archive/2013/06":
         * r.year === "2013"
         * r.month === "06"
         */
    }
}

Embedded parameters always use the pattern :name=pattern: where name is the identifier of the parameters and pattern is a regular expression. In fact, the whole route pattern is a regular expression, but the variable parts should be captured as parameters. Otherwise, the reverse matching is not possible. Also, input strings should not contain substrings that would be mistaken as parameter placeholders. So, avoid URLs with things like ":foo=bar/123:".

An extra callback can be provided to the match call that will be executed after all other callback have fired AND the last one did call next(). It gets the routing object as the onyl argument:

rh = new Rhombus();
rh.addRoute({
    name: "foo",
    pattern: "/foo",
    callback: function(r, next) {
        r.foo = true;
        next();
    }
});

rh.match("/foo", {}, function(r) {
    //r.foo === true
});

###Reverse matching

To avoid hard coding links like "/blog/archive/" + year + "/" + month in your application you can just generate these strings. The route that you want to generate is identified by the names of all it's the hierarchy levels separated by ".":

// to get the URL of the archive page for March 2011 in the above example:
var url = Rhombus.gen('blog.archive', {year: "2011", month: "03"});

// url === "/archive/2011/03"

###Adding Routes

You can add routes at runtime:

var rh = new Rhombus();
rh.addRoute({
    name: "profile",
    pattern: "^/profile/:user_id=\\d+:"
    callback: function(r, next) {
        //render profile page for user `r.user_id`
    }
});

###Removing routes

Routes can be removed by their full hierarchical identifier. To remove the archive page from the above blog example:

rh.removeRoute('blog.archive');

To clear all routes, call:

rh.clearRoutes();

###Matching multiple routes

It is possible for an input string to match multiple routes. In this case, ALL matched callbacks are called. This is intended and can be useful in event routing. For matching URLs to pages however, you should ensure that routes are not ambiguous and lead to only one callback for each input string.