Mr. Router
A simple and lightweight router for use in the browser. Great with React or other front-end application frameworks. Supports callbacks for navigating away from hash changes to prevent change from occurring, and more.
Built using Ben "Cowboy" Allman's super awesome JavaScript Basic Route Matcher.
Example Usage
// Set routesmr; // Set handlersmr; // Route to specified route, by key (calls the appropriate controller).mr; // Change hash on page to specified route, but do not actually route (does not call the controller).mr; // Route by reading from page hash and finding a match in Router.routes.// If a match is found, returns `true`. Otherwise, it returns `false`.mr; // Register a callback when hash changesmr; // Un-register callbackmr; // Get route object from hash, if match is foundmr; //returns {id: 'Task', params: {id: 123}}
Installation
npm i mr-router
Then import to include in your webpack build:
//do things with mr heremr;
Manual Installation
See the Releases.
MrRouter; //or whatever's clever
API
route()
Routes based on current hash. Returns true
if there was a match, false
otherwise. Any callbacks set using setOnHashChange
are ignored.
status()
Returns an object which represents the current hash.
go(id {string}, params {object}, doNotRoute {boolean=})
Changes the hash, which then is handled by onHashChange, which calls the controller.
doNotRoute
is optional. If true, the hash is changed without calling any matching controller, andnavigateAwayCallback
is ignored.
getObjFromHash(hash {string})
Given the specified hash string, if a match was found in Router.routes, it returns an object, ex: {id: 'blah', params:{}}
. Returns false if no
match was found.
setRoutes(map {object})
Sets or adds the routes given. Will override if any duplicates are present. It extends
the route map with Object.assign()
.
mr.setRoutes({foo: 'bar'});
mr.setRoutes({boo: 'nar'});
mr.getRoutes(); // {foo: 'bar', boo: 'nar'}
setControllers(map {object})
Sets or adds the controllers given. Will override if any duplicates are present. It extends
the route map with Object.assign()
.
mr.setControllers({foo: [function]});
mr.setControllers({boo: [function]});
mr.getControllers(); // {foo: [function], boo: [function]}
setOnHashChange([function])
Sets a callback to fire on hash changes. If that callback returns false
, then the hash change is undone (window.history.go(-1)
is called). This is great for preventing loss of unsaved changes in a dialog box, for example.
clearRoutes()
Clears the routes.
clearControllers()
Clears the controllers.
Route matching
For more details on how we match routes to/from hashes, please see the documentation for RouteMatcher.
License
MIT. Free to use in all your things!
Contribution
DO IT! PR's welcome.