cerebral-module-router

An opinionated URL change handler for Cerebral

Programming language: JavaScript

License: MIT License

Tags: Code Design     Router     Cerebral     Mvc    

Latest version: v0.17.1

README

cerebral-module-router

An opinionated URL change handler for Cerebral 1.x

For Cerebral 2 use @cerebral/router instead.

How to use

Go to 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)
  };
}

Preserving payload type

We suppose that router usage should be safe. We can't be sure that nothing will break if we pass String instead of Number or Boolean to signal payload when triggering signal from url. Thats why router will preserve types when stringifying payload to url. But it can cause "unexpected" appear of %3A entries in url. Cast your payload param that appears in url path part to string if you do not want to %3A to appear in url. It is your responsibility to make sure that your action deal with String as you expected.

Given that you still be able to disable router at any time.

Queries powered with urlon

Path-to-regexp is pretty powerfull, but sometimes you want your url would hold more information to pass your app. Usually it is done through queries. Using the same considerations as in previous point we decided that types should be preserved. We can enable query support with urlon super powers of stringify/pasrse any JSON compatible object (any payload can be passed to signal, as fact). Just pass query: true to router options and any payload not defined in path part would be stringified to query part. It is not easy to construct urlon queries by hands, but you never had to. Just keep reading.

Create links

Most times you need to have a links in app. It enables sharing url, opening url in new tab, etc. You can use getSignalUrl method exposed by router to avoid hardcoding urls within app. Please follow your view package documentation to see if it already have component to make a links. Feel free to create an issue on that package otherwise.

Link component will fallback to onClick event handler if router is absent. So you can disable router at any time even if you are using links.