stateful-controller-browser-router

A client-side router for stateful-controller using the history API

Examples

Read the documentation for stateful-controller first. This example assumes you are using browserify.

Constructing a new Router:

var Router = require('stateful-controller-browser-router');
var Controller = require('stateful-controller');
var window = global.window;
var document = window.document;
var frontController = new Controller();

frontController.enterFoo = function(state, upgrade)
{
	if (upgrade)
	{
		document.body.textContent += ' (from the server!)';
		return;
	}

	document.body.textContent = 'Welcome to foo!';
};

// A Router is not an URL mapper: you will have to provide your own.
var urlStateMap = {
	fromURL: function(path)
	{
		if (path === '/foo')
		{
			return ['foo'];
		}

		return ['pageNotFound']
	},
	toURL: function(stateList)
	{
		if (stateList[0] === 'foo')
		{
			return '/foo';
		}

		throw Error('Unknown state(s)');
	}
};

var router = new Router(window, urlStateMap, frontController);

Upgrading

If the current page represents a state that was generated by the server, and you would like to upgrade it:

// Perform an "upgrade" transition by looking at the current location URL
router.upgradeInitialState();

popstate event

To handle the popstate event (which is fired by the browser if the user uses the back/forward/etc button) you will need to:

// Register the `popstate` event
router.attachPopStateListener();

enterStates

You can trigger state transitions from code (useful for links and buttons). This will update the browser history and the current URL in the location bar:

// Note: Will reject if a state transition is already in progress
router.enterStates(['bar']).then(function()
{
	console.log('Done!');
});

queueEnterStates

A user might trigger a state transition while a previous one is still in progress. In this case you might want to defer/queue this new transition.

// This method will not reject if a state transition is already in progress,
// instead it will trigger this new state right after the previous one has completed.
// If this method is called multiple times, only the last one will be executed.
// (however the promise returned will always resolve)
router.queueEnterStates(['baz']).then(function()
{
	console.log('Done!');
});

replaceStateList

Sometimes you will want to change the URL in the location bar without transitioning to a new state:

router.replaceStateList(['foo', 'bar']);