riotgear-router
v1.3.1
Published
State based router for Riot apps
Downloads
3
Readme
rgRouter
RiotGear Router provides Riot apps with state based routes and URL management via the HTML History API.
Install
npm install riotgear-router --save
Include the router in any tag you want to access the router from by "mixin" it in like so:
this.mixin('rg.router')
Once you are happy to start the router call the start() function from either a tag:
this.router.start()
or via the rg
object:
rg.router.start()
The router does not start automatically.
API
After adding the router your tag will have access to the router
via this.router
.
Fluent API Interface
If you want you can chain function calls together. For example:
rg.router.add().start().go()
To #! or to not #!
By default the router uses #!
, however you can change this easily by setting rg.router.hash
to some other value.
.add()
You can add states at any point in time, on mount, on update, on click, on resolve of a promise...whenever.
this.router.add({
name: 'about',
url: '/about',
history: false,
resolve: () => new Promise(function (resolve, reject) {
window.setTimeout(resolve, 2000)
})
})
name
is required, is the name of the state and the identifier to use when calling go()url
is optional. It will update the browser URL on state changehistory
is optional. Set it tofalse
to prevent the state from being added to your browser historyresolve
is optional. The router will wait for.then()
on the resolve function before going to the next state
If you do not specify a url
the browser back and forward buttons will still work.
States names need to be unique. You can add a state with the same name but it will overwrite the state stored by the router.
/:state/:parameters
You can use template patterns like this:
rg.router.add({
name: 'rest',
url: '/:collection/:id/:action'
})
When the router starts it matches the URL with a state.
/users/470129/edit
will match against '/:collection/:id/:action'
If successful the router will create a params
object on the state and copy the values across which you can gain access to via the go
event.
e.g.
this.router.on('go', state = > {
state.params.collection // users
state.params.id // 470129
state.params.edit // edit
})
The template can be anything you'd like, for instance /about/:page
or /alerts/:type/viewable
.
A parameter is prefixed with :
.
When you call go()
you can pass the state a params object that the router uses to construct the URL.
inherit.state.data
You can add whatever you want to a state and get access to it via this.router.current
from within your tag, for example:
this.router.add({
name: 'about',
title: 'About our website' // this.router.current.title
})
You can also inherit the data from parent states by using dot notation in the state name:
this.router.add({
name: 'about.people'
})
When you go to about.people
you will still have the title value available via this.router.current.title
that was set on the about
state.
The history
option is also inherited so if you want a child state to be part of the browser history reset it to true.
Beware that the resolve
function is also inherited. So if you navigate to a state whose parent is set to wait for a promise to resolve then the child will wait too. You can overwrite this by setting resolve to null on the child.
.remove()
this.router.remove('about')
Just as with adding, you can remove states whenever you want in the lifecycle of your application.
.go()
this.router.go('users', params)
Call go()
if you want to change state. Calling go will update the current state, and if a URL is specified will update the URL on the browser.
If you specify a state name that doesn't exist the router will throw you an error.
The router will ignore attempts to go to the same state in succession.
Calling go()
will trigger an update on any tag the router is on via the mixin
The router will update the URL based on the template URL on the state and the structure of the params
object.
.stop()
this.router.stop()
If you want to stop the router and switch to use a different one this function will remove the event listeners and set active
to false.
.start()
this.router.start()
On start the router will check the URL, match it with a state and call go()
. The router does not start automatically. Refreshing the browser will only return you to a state that has a URL. URL-less states can't be refreshed.
.active
this.router.active
Check to see if the router is running or whether it has been stopped.
.current
this.router.current
Current state the router is in. This will contain everything specified on the state as part of the add()
function.
.on('add remove go start stop')
this.router.on('add', state = > console.log(state))
this.router.on('remove', state = > console.log(state))
this.router.on('go', (current, previous) = > console.log(current, previous))
this.router.on('start')
this.router.on('stop')
The router is an observable and will trigger an event for each of the above API calls.