An opinionated URL change handler for Cerebral

cerebral-module-router

An opinionated URL change handler for Cerebral 1.x

For Cerebral 2 use @cerebral/router instead.

How to use

http://cerebral-website.herokuapp.com/documentation/cerebral-module-router

How it works

The Cerebral Router is one of the least invasive routers out there.
You can attach the router module to already written cerebral application and it will just work.
And you will be able to disable router completely in environments where you do not need it at all(eg, React Native app).

Though we are making few considerations:

Signal bound to route should be treated as potential entry point. Make sure that your signal would be able to run on app start.
Your app will prepare initial state either during server side rendering or within signals ran in sync with modulesLoaded event.

Addressbar updates while navigating an app

Router listens to signalTrigger and signalStart events.
Addressbar will be updated if signal is bound to route in config.
Router uses url-mapper's stringify method to get url from given route and signal payload.

Trigger correspondent signal with payload while normal app startup

Router listens to modulesLoaded event and schedules correspondent signal trigger if there was no predefined signal execution (see below).
Router uses url-mapper's map method to get matched signal and payload to pass.
Matched signal trigger would be delayed until signals started by other modules on modulesLoaded event is finished, if any.

Trigger correspondent signal on history traversal (back and forward navigation)

Router listens history traversal events using addressbar library.
It would trigger matched signal if url has changed.

Just works with `devtools` time traveling and `recorder`

Both devtools and recorder uses internal cerebral mechanism of predefined signal run.
Router will update addressbar if any predefined signal was bound to route.
So your addressbar will be kept in sync even using recordings and time travel debugging.

Routes config

Routes config is object passed as first argument.
Use path-to-regexp format routes as keys and signal name to bound as value.
Use '/*' as key to make a catch all route definition.
You can nest config object. Route will be concatenation of keys:

Router({
  '/foo': 'foo',   // `/foo` <==> `foo`
  '/bar': {
    '': 'bar',     // `/bar` <==> `bar`
    '/baz': 'baz'  // `/bar/baz` <==> `baz`
  }
})

Application startup

As said before router will autodetect any signal ran in sync with modulesLoaded event.
Router will not trigger if there was remembering of state occured before modulesLoaded event.
We strongly recommend not to run your initial signals in that case too.

You can set some isLoaded flag in state store within initial signal and chech it before run.
Or remove modulesLoaded event listener if there was predefinedSignal emitted.

import NewTodo from './modules/NewTodo';
import List from './modules/List';
import Footer from './modules/Footer';

import appStarted from './signals/appStarted';

export default (options = {}) => {
  return (module, controller) => {

    module.modules({
      new: NewTodo(),
      list: List(),
      footer: Footer()
    });

    module.signals({
      appStarted
    })

    function init () {
      controller.getSignals().app.appStarted({}, { isSync: true });
    }

    controller.once('predefinedSignal', function () {
      controller.removeListener('modulesLoaded', init)
    })

    controller.once('modulesLoaded', init)
  };
}