Functional client-side router in ~570 bytes, built on HTML5 History API
You might also be interested in mitt - a 200 bytes event emitter, and hyperapp - build rich UI apps with 1kb.
✨ Pull requests for client-side tests or any other features/fixes are welcome! 🚀
Table of Contents
(TOC generated by verb using markdown-toc)
Install
Install with npm
$ npm install gibon --save
or install using yarn
$ yarn add gibon
The UMD build is also available on unpkg CDN
or on RawGit CDN
Usage
For more use-cases see the tests
const router = routerstart
API
router = gibon(routes, onRoute, onClick)
routes
Object with key/value pairs, where key is the route and value should be a function that has (state, params)
signature.
route
- path like/users/:user
value
- function that has(state, params)
signature
The route path syntax is based on the same syntax found in Express.
Example
const userView = { console} const router = routerstart
onRoute - optional
It should be function
that is triggered every time when given route is accessed. Completely optional, but useful for higher level things such as seen in hyperapp.
It is passed with (view, state, el)
signature. See public/dom.js example.
view
- always a function for the routestate
- value that is passed as second argument to .render() methodel
- previous dom element (ifbel
is used for example) orundefined
Example
const html = const state = title: 'Welcome!' const routes = html` ` // some entry pointconst main = document const helper = { return parent} const onRoute = { return } const router = routerstart
For complete working example see public/nanomorph.js, which uses nanomorph to do the diffing and updating only needed dom elements.
onClick - optional
It should be function
that controls behaviour of clicking on links. We intercept all <a href="/path">...</a>
clicks. If you want to opt out of this, add the custom attribute data-no-routing
to any anchor element that should be handled differently.
It is passed with (e, render)
signature.
e
- the clickeda
elementrender
- function which is the .render() method
All that just means that it is perfectly configured by default to work on pushState servers, so page won't refresh while you move through pages of the defined routes.
Try out some of the provided examples in public/
.
router.start()
Starts the router. Function that starts the router to listen on routes. If you not call it, it won't attach any listeners, so it won't work.
el = router.render(view, state)
We can use .render()
without .start()
ing the router.
You can use that to manually render view
with optional state
. It returns what the view returns, so if
the view returns a DOM element, then el
will be that element.
view
- string path to route, or function likeuserView
state
- optional, any value that you want
Example 1
const router = const userView = { console} router
The cool thing comes when you use some Virtual or Real DOM builder, such as bel or hyperx.
In the next example we are using bel
to define some HTML without breaking the JavaScript and we "render" some specific route with some context/state, and finally we append it ot the page body.
Example 2
const html = const router = const el = routerdocumentbody
So we'll get such that div in the document body
hello world user is tunnckoCore
Examples
Run some of the examples by cloning the repo and calling them through npm scripts
npm run example:nanomorph
npm run example:simple
npm run example:dom
Related
- always-done: Handle completion and errors with elegance! Support for streams, callbacks, promises, child processes, async/await and sync functions. A drop-in replacement… more | homepage
- bel: A simple extension to native elements | homepage
- hyperapp: 1kb JavaScript library for building frontend applications. | homepage
- hyperx: tagged template string virtual dom builder | homepage
- minibase: Minimalist alternative for Base. Build complex APIs with small units called plugins. Works well with most of the already existing… more | homepage
- nanomorph: Hyper fast diffing algorithm for real DOM nodes | homepage
- redom: Tiny DOM library | homepage
- try-catch-core: Low-level package to handle completion and errors of sync or asynchronous functions, using once and dezalgo libs. Useful for and… more | homepage
Contributing
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Please read the contributing guidelines for advice on opening issues, pull requests, and coding standards.
If you need some help and can spent some cash, feel free to contact me at CodeMentor.io too.
In short: If you want to contribute to that project, please follow these things
- Please DO NOT edit README.md, CHANGELOG.md and .verb.md files. See "Building docs" section.
- Ensure anything is okey by installing the dependencies and run the tests. See "Running tests" section.
- Always use
npm run commit
to commit changes instead ofgit commit
, because it is interactive and user-friendly. It uses commitizen behind the scenes, which follows Conventional Changelog idealogy. - Do NOT bump the version in package.json. For that we use
npm run release
, which is standard-version and follows Conventional Changelog idealogy.
Thanks a lot! :)
Building docs
Documentation and that readme is generated using verb-generate-readme, which is a verb generator, so you need to install both of them and then run verb
command like that
$ npm install verbose/verb#dev verb-generate-readme --global && verb
Please don't edit the README directly. Any changes to the readme must be made in .verb.md.
Running tests
Clone repository and run the following in that cloned directory
$ npm install && npm test
Author
Charlike Mike Reagent
License
Copyright © 2016-2017, Charlike Mike Reagent. MIT
This file was generated by verb-generate-readme, v0.6.0, on May 04, 2017.
Project scaffolded using charlike cli.