Simrou 1.2

A very tiny hash-based JavaScript routing system

Simrou is a small javascript framework, that allows to bind action handlers to window.location.hash. This is in particular useful for the development of single-page web applications. See the demo code below to get an idea of how this works.

In contrary to other frameworks with similar features, Simrou is intended to be very simple to setup and use. It does not provide any other features beside the routing - therefore it is very lightweight and flexible.

Demo

$(function() {
    // Setup an instance of Simrou
    var router = new Simrou();
    
    // Register a route that matches all edit requests to your articles
    var editRoute = router.addRoute('/article/:id/edit');
    
    // Bind an action handler to that route
    editRoute.get(function(eventObject, method, id) {
        showEditForm(id);
    });
    
    // HTML Forms are getting watched, so we can bind an action handler
    // to POST requests to that same route
    editRoute.post(function(eventObject, method, id) {
	    saveChanges(id);
    });
    
    // Get the router running...
    router.start();
    
    // Navigate somewhere (updates location.hash and resolves the URL)
    router.navigate('/article/42/edit');
    
    // ..or resolve without touching location.hash
    router.resolve('/article/18/edit', 'POST');
});

Links work just as expected if you prepend them with a hash symbol:

<a href="#/article/182/edit">Edit article 182</a>

A typical url within your application will look like this:

http://your-domain.tld/some/path.html#/article/182/edit

Advanced usage

You can add more than one route or action handler at a time:

$(function() {
    var router = new Simrou({
        '/article/:id/edit': {
            get: [ actionHandler11, actionHandler12 ],
            post: actionHandler2,
            put: actionHandler3
        },
        '/downloads/*': {
            get: actionHandler4
        },
        '/homepage': actionHandler5
    });
    
    router.start('/homepage');   // Handing over a default route to navigate to
});

You can use two different types of wildcards in your routes: Parameters and Splats (this is just the same as in Backbone.js).

• Parameters are introduced by a colon and end at the next slash.
  e.g. "/test/:name" matches "/test/mike" and "/test/joe", but not "/test/joe/something".

• Splats start with an asterix and may optionally be followed by a name.
  e.g. "/test/*sp" matches "/test/joe" (extracting "joe") and "/test/joe/something/more" (extracting "joe/something/more").

Parameters and splats can be mixed:

var articleRoute = router.addRoute('/articles/:edit/*action');

Any action handler attached to this route will be called with the following arguments:

function actionHandler(event, method, edit, action)

• event is a jQuery event object.
• method is a string such as 'get' or 'post', specifing the desired HTTP method.
• edit and action are the values extracted from the route.

The route object provides a nifty helper method to get a concrete url:

var article = router.addRoute('/articles/:id/*action');
var url = article.assemble(17, 'edit'); // returns: /articles/17/edit

Action handlers can be attached via jQuery events instead of using Simrou's attachAction() method:

var route = router.addRoute('some/route');

// This..
$(route).on('simrou:get', eventHandler);

// ..equals:
route.get(eventHandler);

If you want to catch a route regardless which HTTP method was intended, you can do that as well:

route.attachAction(function() {
    // ..do awesome stuff..
});

Requirements & License

Simrou requires jQuery 1.7 or newer and is released under the MIT license.

Internally, Simrou binds itself to the onHashChange event. If you want to include a fallback for older browser or the IE, Simrou works out of the box with Ben Alman's HashChange Plugin for jQuery. No setup required.