@composi/router
v1.0.1
Published
A router for @composi/core, allowing conditional rendering of functional components on the client side for SPAs and PWAs.
Downloads
9
Maintainers
Readme
@composi/router
@composi/router is a client-side hash-based router for single page apps (SPA). This is for those occasions where you want to be able to conditionally render a set of sub components based on a url value. This is works properly with the browser's back button and you can use it with the History API. @composi/router is very simple with only a few options. If you need a more advanced router, check out Universal Router. Or use whatever router you prefer.
Installation
npm i -D @composi/router
Import and Use
Import Router
into your app.js
file:
import { h, render } from '@composi/core'
import { Router } from '@composi/router'
To create routes you need to instatiate Router and provide it with a series of path objects separated by commas. The path object is an object literal with a path and action value.
Adding Routes
The following example shows how to set up routes. What you do when the route happens is completely up to you:
import { h, render } from '@composi/core'
import { Router } from '@composi/router'
// Create instance of Router:
const router = new Router()
// Define paths to use:
router(
{
path: "/",
action: () => {
// Do something when main page loads
}
},
{
path: "/about",
action: () => {
// load an "About" widget
}
},
{
// Capture a parameter id:
path: "/users/:name",
action: (name) => {
if (name === 'joe') alert('Hi, Joe!')
else console.log(name)
}
}
)
Normally you would use a route to handle loading a component. The easiest way to do this is to use a functional component:
import { h, render } from '@composi/core'
import { Router } from '@composi/router'
const router = new Router()
const Home = <h1>This is Home</h1>
const FirstPage = <h1>Welcome to the First Page!</h1>
const SecondPage = <h1>Second Page Here.</h1>
function Menu(props, child) {
return (
<div>
<ul class='menu'>
<li><a href="#/">Home</a></li>
<li><a href="#/first">First Page</a></li>
<li><a href="#/second">Second Page</a></li>
</ul>
{
child
}
</div>
)
}
function renderPage(component) {
render(<Menu>{component}</Menu>, 'section')
}
router(
{
path: '/',
action: () => renderPage(Home)
},
{
path: '/first',
action: () => renderPage(FirstPage)
},
{
path: '/second',
action: () => renderPage(SecondPage)
},
{
path: '/*',
action: () => {
console.log('Sorry, not a proper path.')
}
}
)
render(<Menu>{Home}</Menu>, 'section')
You could also use routes in conjuction with @composi/datastore. The route would set a value on the dataStore, which would cause the component to update.
Multiple Handlers for One Route
You can use more than one handler for a route. You might do this because you need to remove some functionality later. If that's the case, you want to use named handlers for any handler you will want to remove:
// Handler to delete later:
const removableHandler = () => {
console.log('This handler is temporary and subject to removal.')
}
router(
{
path: '/',
action: () => console.log('You are home!')
},
{
path: '/',
action: () => console.log('This is another handler on the Home path.')
}
)
To learn more about removing paths and handlers, see Removing a Route
Optional Parameters
You can indicate that a parameter is optional by using the ?
character after it:
router({
path: 'users/:name?',
action: function(name) {
if (name) {
console.log(name)
} else {
console.log('No name was provided.')
}
}
})
router.navigate('users/') // logs `No name was provided.`
router.navigate('users/bob') // logs `'bob'`
Wildcard
Using *
will catch any routes that do not match previously defined routes. Use this as a catch all for any unexpected routes or for a 404:
router({
path: 'users/*',
action: function() {
console.log('Caught unexpected route!')
}
})
router.navigate('users/12312312')
Block a Route
You can block a route by returning false:
router({
path: '/admin',
action: function() {
return false
}
})
Remove All Routes and Handlers
If you want to remove all current routes and handlers, you can invokde the following:
router.removeAll()
After running that none of the paths will work.
Removing a Route
You can remove a singular route as follows:
// Handler to delete later:
const removableHandler = () => {
console.log('This handler is temporary and subject to removal.')
}
router(
{
path: '/',
action: () => console.log('You are home!')
},
{
path: '/',
action: () => removableHandler
}
)
// Sometime later we remove the named handler:
router.remove('/', removableHandler)