riouter
v2.0.0
Published
Riot.js router.
Downloads
9
Maintainers
Readme
Riouter
Riot.js router.
Differences with @riot/route
- Riouter can have multiple router instances on a single page. Even a router within a route is possible.
- Riouter can control whether the browsers session history is changed by the router.
- Riouter does not have a
initDomListeners
method. (It is trivial to write a solution yourself, see the usage example below or theexample/src/app.html
'sonRouterStart
function.)
Install
npm install riouter
OR
yarn add riouter
Usage
<app>
<router base="{ window.location.href }" onStarted="{ onRouterStarted }">
<nav>
<button route="home">
Home
</button>
<button route="about">
About
</button>
</nav>
<route path="home">
Home page
</route>
<route path="about">
About page
</route>
</router>
<script>
// Import router components.
import { router, route } from 'riouter'
export default {
components: {
// Router.
route: route,
router: router,
},
onRouterStarted(routerComponent, router) {
this.$('router')
.addEventListener('click', (event) => {
// Check if click is relevant.
const target = event.target.closest('button[route]')
if (!target) {
return
}
event.preventDefault()
// Check if route is not already active.
const targetRoute = target.getAttribute('route')
if (targetRoute === this.state.activeRoute) {
return
}
// Invoke route change.
this.state.activeRoute = targetRoute
router.push(this.state.activeRoute)
})
// Set initial router path to 'home'.
this.state.activeRoute = 'home'
router.push(this.state.activeRoute)
},
}
</script>
</app>
API
router (component)
The router
component wraps the <route>
s and will manage whether they are active or not based on the state of the router. The component has the following attributes:
base
: Base path of the application.- Default:
''
- Type: String
- Default:
updateHistory
: Whether to update the History API.- Default:
false
- Type: Boolean
- Default:
onBeforeStart
: Called after the router is set up, but before the slot is mounted.- Default:
null
- Type: Function
- Parameters:
- Router component.
- Router instance used by router.
- Default:
onStarted
: Called after the slot has been mouted.- Default:
null
- Type: Function
- Parameters:
- Router component.
- Router instance used by router.
- Default:
route (component)
The route
component wraps the content that should be visible when the acompyoning route is active. The component has the following attributes:
path
: The path to which the URL should match for this route to become active.- Required:
true
- Type: String
- Required:
onBeforeMount
: Lifecycle function called before the rout is mounted.- Default:
null
- Type: Function
- Parameters:
- Route component.
- Router instance used by router.
- Route's path.
- Default:
onMounted
: Lifecycle function called after the rout is mounted.- Default:
null
- Type: Function
- Parameters:
- Route component.
- Router instance used by router.
- Route's path.
- Default:
onBeforeUnmount
: Lifecycle function called before the rout is unmounted.- Default:
null
- Type: Function
- Parameters:
- Route component.
- Router instance used by router.
- Route's path.
- Default:
onUnmounted
: Lifecycle function called after the rout is unmounted.- Default:
null
- Type: Function
- Parameters:
- Route component.
- Router instance used by router.
- Route's path.
- Default:
Router
Underneath the router
and route
components use a router to manage its state. The instance used can be interacted with by listening to the events of the components. The router extends the Dispatcher and has the following functions:
constructor
: Creates a router instance.- Parameters
options
: Options for the router.- Default:
null
- Type: Object
- Properties:
basePath
: Base path of the application.- Default:
''
- Type: String
- Default:
updateHistory
: Whether to update the History API.- Default:
false
- Type: Boolean
- Default:
pathToRegexp
: Options for path-to-regexp.- Default:
{}
- Type: Object
- Default:
- Default:
- Parameters
destroy
: Destory instance.getPath
: Get the current path.- Returns: The current path.
- Type: String
- Returns: The current path.
getRoute
: Get the current route.- Returns: The current route.
- Type: String
- Returns: The current route.
addRoute
: Add route to router.- Parameters
path
: Route's path.- Required: true
- Type: String
options
: Options for path-to-regexp.- Default:
{}
- Type: Object
- Default:
- Parameters
removeRoute
: Remove route from router.- Parameters
path
: Route's path.- Required: true
- Type: String
- Parameters
getRoutes
: Get all routes part of the router.- Returns: Array of strings, all paths of routes in router.
push
: Push path to router, potentially changing active router.- Parameters
path
: Path to push.- Required: true
- Type: String
- Returns: Boolean, whether a matching route was found.
- Parameters
The router dispatches the following events:
added
: Dispatched when a new route has been added to the router usingaddRoute
.- Data:
route
: The path of the added route.- Type: String
router
: The router instance to which the route has been added.- Type: Router
- Data:
pushed
: Dispatched when a new path has been pushed to the router usingpush
.- Data:
path
: The path which has been pushed.- Type: String
router
: The router instance to which the path has been pushed.- Type: Router
route
: The route matching the path.- Type: String
- Data:
The router can be used seperatly from the components by importing the
Router.js
file in the root of the project:import Router from 'riouter/Router.js'
.
Dispatcher
The Dispatcher
class is extended by the Router
class and deals with handling and dispatching events. It has the following functions:
constructor
: Creates a dispatcher instance.destroy
: Destory instance.addListener
: Start listening to the named event.- Parameters
name
: Event name.- Required: true
- Type: String
callback
: Callback function.- Required: true
- Type: Function
- Parameters
removeListener
: Stop listening to the named event.- Parameters
name
: Event name.- Required: true
- Type: String
callback
: Callback function.- Required: true
- Type: Function
- Parameters
removeAllListeners
: Remove all listeners listening to the dispatcher or just the named events.- Parameters
name
: Event name.- Default:
null
- Type: String
- Default:
- Parameters
dispatch
: Invokes the callback functions matching the event name.- Parameters
name
: Event name.- Required: true
- Type: String
...data
: Data for callback.- Required: false
- Type: Any
- Parameters
Lazy loading with @riotjs/lazy
The router also supports lazy loading. Simply use @riotjs/lazy as you would otherwise. The components will be lazily loaded once the route they are part of becomes active.
<app>
<router base="{ window.location.href }" onStarted="{ onRouterStarted }">
<nav>
<button route="home">
Home
</button>
<button route="about">
About
</button>
</nav>
<route path="home">
<home />
</route>
<route path="about">
<about />
</route>
</router>
<script>
// Import riot lazy.
import lazy from '@riotjs/lazy'
// Import router components.
import { router, route } from 'riouter'
export default {
components: {
// Router.
route: route,
router: router,
// Pages.
home: lazy(() => import('./home.riot')),
about: lazy(() => import('./about.riot')),
},
onRouterStarted(routerComponent, router) {
// Listen to clicks and update router. See example above.
}
}
</script>
</app>