123 lines
3.7 KiB
Markdown
123 lines
3.7 KiB
Markdown
# Router
|
|
|
|
Router encompases the core functions of a router. It is designed to be slim and have an
|
|
easy-to-read, yet powerful API.
|
|
|
|
**NOTE** This router is geared toward offline-first apps and thus does not support pushState.
|
|
|
|
# Usage
|
|
|
|
## Instantiation
|
|
|
|
```js
|
|
const router = Router(routeSpecArray, rootURL='#'):
|
|
```
|
|
|
|
### routeSpecArray
|
|
|
|
An array of objects with the following properties:
|
|
|
|
- `name` _string_ - an optional string that can be referred to in the `href` and `goto` instance
|
|
methods. Duplicate names are not allowed.
|
|
|
|
- `path` _string_ - the path template for this route. Path templates are matched in the order of the
|
|
array. Example:
|
|
|
|
`"/"` - for the root path `"/articles"` - another static path `"/article/:id"` - a path with a
|
|
variable `"/:unknownRoute"` - the last route could catch erroneous routes. Unmatched urls will
|
|
automatically route here.
|
|
|
|
- `vars` _object_ - an optional object mapping variable names in the path template to a regular
|
|
expression for validation
|
|
|
|
- `enter` _function_ - a function for when this route is entered. The `enter` function receives two
|
|
parameters:
|
|
|
|
- _route instance object_ - this is a object that contains properties:
|
|
|
|
- `name` _string_ - the route name
|
|
- `vars` _object_ - an object holding any variables parsed from the path
|
|
- `path` _string_ - the path as received
|
|
|
|
- _router instance object_ - (see below)
|
|
|
|
The `enter` function may return a callback that will be called instead of the `enter` function for
|
|
further navigate events that will be handled by this route (with different variables). This allows
|
|
`enter` to establish a context for the route it handles.
|
|
|
|
- `exit` _function_ - an optional function that will be called before calling `enter` of the next
|
|
path. `exit` has the option to delay the call to `enter` by returning a promise. This is intended
|
|
for handling transition animations. If the route's `enter` function returns a callback, `exit`
|
|
will not be called if the same route receives navigation but with different variables. `exit`
|
|
receives the parameters similarly to `enter`:
|
|
|
|
- _route instance object_ - for the route being exited
|
|
- _route instance object_ - for the route yet-to-be entered
|
|
- _router instance object_ - (see below)
|
|
|
|
### rootURL (optional string)
|
|
|
|
The url prefix of all paths. This should always be `#` unless you're nesting routers.
|
|
|
|
### router (returned object)
|
|
|
|
The returned instance provides these methods:
|
|
|
|
- `goto(url: string)` or `goto(pathName: string, vars: object)`
|
|
|
|
Match to a route by relative url or pathName and a vars object. Navigate there.
|
|
|
|
- `href(pathName: string, vars: object)`
|
|
|
|
Build a relative url based on the name and supplied vars.
|
|
|
|
- `start(initialRoute: string)`
|
|
|
|
Listen to `window.onhashchange` for route changes. The `initialRoute` will be passed to `goto()`
|
|
if there is no current route in `window.location`.
|
|
|
|
- `stop()`
|
|
|
|
Cancel subscription to `window.onhashchange`
|
|
|
|
- `current()`
|
|
|
|
Get the current _route instance object_ as was provided to the current routes `enter` function.
|
|
|
|
Example:
|
|
|
|
```js
|
|
const router = Router([
|
|
{
|
|
name: 'home',
|
|
path: '/',
|
|
enter: (r, route) => {
|
|
console.log('At application home');
|
|
},
|
|
exit: (r, route, newRoute) => {
|
|
console.log(`Exiting from ${route.path} to ${newRoute.path}`);
|
|
}
|
|
},
|
|
{
|
|
name: 'article',
|
|
path: '/article/:id',
|
|
vars: { id: /[a-f0-9]{6,40}/ },
|
|
enter: (route, router) => {
|
|
console.log('Opening Article', route.vars.id);
|
|
return (route, router) => {
|
|
console.log('Opening Article', route.vars.id);
|
|
};
|
|
},
|
|
exit: (route, newRoute, router) => {
|
|
console.log('Closing Article', route.vars.id);
|
|
}
|
|
},
|
|
{
|
|
id: '404',
|
|
path: ':vars',
|
|
enter: r => r.goto('home')
|
|
}
|
|
]);
|
|
router.start('/');
|
|
```
|