web-router

route-history

route-history enhances the browser's history api by...

1. allowing route data to be matched to the pathname in the url
2. having route changes run through a series of middleware functions that can cancel or redirect
3. keeping a list of all route changes
4. allowing other components to listen to when routes are in the process of changing and when they have changed

applyRoutes

The applyRoutes method allows the router to associate the url with some sort of route data. The route data can be pretty much anything, but there are a few key properties.

pattern

This value is matched with location.pathname to associate the current url with the route data. Parameters can specified by :paramName. Optional parts can be surrounded by parentheses.

/some-route
/some-route-with-param/:id
/some-route-with-optional(/:id)

title

If this value is defined, the router will use it to set the document's title property.

applyMiddleware

A middleware function will have an action, nextRoute, and prevRoute arguments. To continue the route change call action.ok(). To abort the route change call action.cancel(). To redirect the route change, call action.redirect( '/some-other-url' ). All three methods take an optional state parameter that can be used to pass additional data.

import { routeHistory } from 'route-history';

const middleware = [
    // Redirect Root to Login or Home
    ( action, nextRoute, prevRoute ) => {
        if ( nextRoute.pathname === '' || nextRoute.pathname === '/' ) {
            if ( authenticated() ) { 
                action.redirect( '/home' );
            } else {
                action.redirect( '/login' );
            }
            
        } else {
            action.ok();
        }
    }, 

    // Redirect to Login When Not Authenticated
    ( action, nextRoute, prevRoute ) => {
        if ( !authenticated() && nextRoute.match && !nextRoute.match.allowAnonymous ) {
            action.redirect( '/login', { props: { redirectTo: nextRoute.pathname } } );
        } else {
            action.ok();
        }
    }
];

routeHistory.applyMiddleware( middleware );

push

The push function adds a new location to the route history.

import { routeHistory } from 'route-history';

routeHistory.push( '/new-location', { props: { someProp: 'someValue' } } ).then( () => {
    // this executes after the route change has been processed.
} );

replace

The replace function replaces the existing location in the route history.

import { routeHistory } from 'route-history';

routeHistory.replace( '/new-location', { props: { someProp: 'someValue' } } ).then( () => {
    // this executes after the route change has been processed.
} );

back

The back function goes back one location in the route history.

import { routeHistory } from 'route-history';

routeHistory.back().then( () => {
    // this executes after the route change has been processed.
} );

go

The go function goes forward or back some delta in the route history.

import { routeHistory } from 'route-history';

routeHistory.go( -2 ).then( () => {
    // this executes after the route change has been processed.
} );

refresh

The refresh function executes any middleware against the current location.

import { routeHistory } from 'route-history';

routeHistory.refresh().then( () => {
    // this executes after the route refresh has been processed.
} );

list

The list function returns an array of all the route location history.

import { routeHistory } from 'route-history';

const routeHistoryList = routeHistory.list();

addEventListener

The addEventListener method allows another chunk of code to listen to when routes are changing or have changed.

import { routeHistory } from 'route-history';

routeHistory.addEventListener( 'changing', () => {
    // this executes at the beginning of a route change.
} );

routeHistory.addEventListener( 'changed', ( action, nextRoute, prevRoute ) => {
    // this executes at the beginning of a route change.
    // action can be "none", "forward", or "back"
} );

removeEventListener

The removeEventListener method allows another chunk of code to stop listening to route changes.

import { routeHistory } from 'route-history';

const unlisten = routeHistory.addEventListener( 'changing', () => {
    // this executes at the beginning of a route change.
} );

unlisten();

const handleChanged = ( action, nextRoute, prevRoute ) => {
    // this executes at the beginning of a route change.
    // action can be "none", "forward", or "back"
} );

routeHistory.addEventListener( 'changed', handleChanged );

routeHistory.removeEventListener( 'changed', handleChanged );