route-reactor

Framework-agnostic client-side router (uses page.js, plays well with React)

Summary

route-reactor is a simple but powerful client-side router built on page.js.

Features:

• uses HTML5 History API by default (includes a polyfill to fall back to hash routing).
• simple route declaration syntax
• customizable error page for errors that occur either in routing or as a result of controller actions
• customizable loading page while data is being fetched for a view
• default support for building views with React
• easily customizable to render view in Handlebars, EJS, etc.
• generous use of assertions and warnings to find bugs early

Installation

Install:

npm install --save route-reactor

Usage

Note that route-reactor is meant for use via browserify or other front-end packagers.

var routeReactor = require('route-reactor');
var router = routeReactor({
  rootEl: document.getElementById('app-container')
});

router.route({
  url: '/',
  name: 'home',
  template: MyReactHomePage,
  initialize: function() {
    this.setProps({
      greeting: 'hello',
      name: 'world'
    });
  }
});

// listen for warning or errors and handle them programmatically
router.on(router.events.WARN, console.log.bind(console));
router.on(router.events.ERROR, function(err) {
  console.warn(err.stack || err.message);
});

router.start();
// => matches 'home' route, renders MyReactHomePage with props {greeting: ..., name: ...} at #app-container

Examples

See the examples/ directory. To run them:

cd route-reactor
npm run build
npm start

And open a browser to localhost

Router API

router.configure({...}) - set options on the router, see below for all available options

router.route({...}) - define a named route:

• .url - the url pattern, eg ('/user/:id')
• .name - a string name for the route (must be unique, eg 'user')
• .template - the React (or other) template to use for this route
• .initialize(query) - a function that takes a parsed URL query object and configures the properties of the view. this is called every time the view is transitioned to. this may return a promise if initialization requires eg XHR
• .uninitialize() - optional, a function that is called whenever the view is transitioned away from. this may return a promise
• .actions - an object literal of key -> function(), with each function being made available as a property. these are the equivalent of controller actions

router.go(url) - navigate to the specified url (eg '/user/123')

router.link(name, params) - returns a URL constructed by interpolating the params into the named route's URL pattern. (eg router.link('user', {id: 123}) will return /user/123. returns null if the named route cannot be found.

Page API

Inside of each page, eg in the initialize() or the actions functions, the value of this is set to a page object. You can change the template or properties at any time and the page will be re-rendered automatically.

page.setProp(key, value) - sets a view property to have a given value. (these become .props of your React view specified in router.route({template: view})). Triggers re-render.

page.setProps({...}) - set multiple props at once. Triggers re-render.

page.getProps() - get the full set of props

page.getProp('key) - get the value of the named prop

page.setTemplate(templateFn) - update the template to use a different one. Triggers re-render.

page.getTemplate() - get the current template

page.getName() - get the page name

page.getURL() - get the page's url pattern

page.rerender() - manually trigger a re-render without changing props

page.catch(err) - if you have custom code running, eg a websocket connection that updates the view, you can use this method to propogate any errors in your code into the router's standard error handling and display.

Router Options

Use the below with router.configure(options)

.rootEl: the root HTMLElement that all pages should be rendered to

.notFoundClass: a React component to display whenever the URL does not match any routes. It should accept two props: message and detail, both strings. message will always be a simple 'not found' message, detail will contain the URL.

.errorClass: a React component that will be displayed whenever an error occurs within the routing.

.loadingClass: a React component that will be displayed when a page transition requires asynchronous resources. It will be displayed until both a) all the resources have loaded and b) the minimum transitionTime has passed.

.transitionTime: the minimum time that the transition page (transitionClass) should be displayed. This is useful for ensuring that if your resources load near instantaneously that you do not have a flash of loading content that will make users think they missed something. Depending on the importance of the message you may want a shorter or longer time. Value should be in milliseconds.

Development Guide

Run tests:

npm test

Run examples, and rebuild code on change:

npm run start &
npm run dev

License

The MIT License (MIT)

Copyright (c) 2014 Joseph Savona

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.