stateful-controller-browser-router

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

Usage no npm install needed!

<script type="module">
  import statefulControllerBrowserRouter from 'https://cdn.skypack.dev/stateful-controller-browser-router';
</script>

README

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']);