Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/arqex/urlhub
Yet another router library, but the simplest one.
https://github.com/arqex/urlhub
frontend router router-library
Last synced: about 1 month ago
JSON representation
Yet another router library, but the simplest one.
- Host: GitHub
- URL: https://github.com/arqex/urlhub
- Owner: arqex
- License: mit
- Created: 2017-04-17T16:34:23.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-02-11T10:45:58.000Z (9 months ago)
- Last Synced: 2024-09-18T10:18:40.132Z (about 2 months ago)
- Topics: frontend, router, router-library
- Language: JavaScript
- Homepage:
- Size: 254 KB
- Stars: 5
- Watchers: 3
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
UrlHub: Yet another router library, but the simplest one
======================================================
[](https://travis-ci.org/arqex/urlhub)
[](http://badge.fury.io/js/urlhub)
Is another new routing library needed? Probably not, UrlHub is a router that make the work like any other javascript routing library. The difference is that **UrlHub is SIMPLE**, it's made to be understood completely just by reading this file.
## Installation
```
npm install urlhub
```
## Translating URLs to other things
Think of UrlHub as **a library to translate URLs into something else** (that's a nice definition for a router). Let's create a test router.
```js
var urlhub = require('urlhub');
var pushStrategy = require('urlhub/pushStrategy');
var routes = [
{path: '/home', cb: 'Sweet Home'},
{path: '/users', cb: 'Users screen', children: [
{path: '/:userId', cb: 'SingleUser'}
]}
];
var router = urlhub.create( {strategy: pushStrategy} );
router.setRoutes( routes );
router.start();
```
The router has been defined with 3 routes:
- `/home`
- `/users`
- `/users/:userId` (Child of `/users`)
The `cb` (named after callback) attribute is what the router returns when a url matches one of the defined routes. With the example above we are translate URLs into `strings`.
```js
location = router.match('/home');
// location.matches will be ["Sweet Home"]
location = router.match('/users/937264923');
// location matches will be ["Users screen", "SingleUser"]
```
The `matches` attribute is the translation of the URL. Since we defined the `"/home"` route with the string `"Sweet home"` as its `cb`, we get that same string back when there is a match on that route. Nested routes will match all the parent routes, that's
why the `matches` attribute is an `array`.
`router.match` returns much more useful information from the url:
```js
location = router.match('/users/937264923?foo=bar#my_hash');
/* location value will be:
{
hash: "#my_hash",
matches: ["Users screen", "SingleUser"],
matchIds: ["/users/", "/users/:userId],
params: {userId: "937264923"},
pathname: "/users/937264923",
query: {foo: 'bar'},
route: "/users/:userId",
search: "?foo=bar"
}
*/
```
As you can see, UrlHub does nothing else than parsing and translating URLs. If we give it a string as `cb` it will be returned on a URL match, but you'd probably want to pass a function as `cb` to be executed after the match, or a React component in order to display it after routing.
## Detecting URL changes
The second nice feature that any router must have is detecting changes in browser's location to react properly to them. That's why we need a **routing strategy**: the mechanism to define what is a URL change, and how to navigate without a page refresh.
There are 2 routing strategies shipped with UrlHub, the [HTML5's pushState strategy](https://developer.mozilla.org/en-US/docs/Web/API/History_API), and the Hash strategy, that updates the URL's hash to navigate. Both strategies are used in the same way by urlhub:
We create our router like this:
```js
var urlhub = require('urlhub');
var hashStrategy = require('urlhub/hashStrategy');
var router = urlhub.create( {strategy: hashStrategy} );
router.setRoutes( routes );
router.onChange( function( location ){
// The location object is the same returned by the `match` method.
// This will be triggered by any change in the browser's URL.
// We can load our content here depending on the route match.
});
// Start listening to URL changes
router.start();
```
## Navigating
UrlHub come with some useful methods to let the developers navigate programmatically without hassle.
```js
// Go to the `/users` path
router.push('/users');
// Replace current location in history by `/users/874922`
router.replace('/users/874922')
// It's possible to use partial location objects to update the route
router.push({query: {foo: 'anotherBar'}})
```
## Intercepting route changes
A nice feature in urlhub is the ability of preventing route changes by using the `onBeforeChange` hook. Imagine that our app has some route '/restricted' that can only be accessed for users that are logged in, we can add this restriction easily:
```js
// The hook function receives the next route as a location object
router.onBeforeChange( function(location){
if( location.pathname === '/restricted' && !userIsLoggedIn() ){
// In this case we go to the login screen
return '/login';
}
// In any other case, don't intercept the route
return location;
})
```
## What else?
That's basically all the functionality. This is still a work in progress, still need:
* Document the API and options.
* There is a `Link` React component shipped. Document it.
* How to use in node.js without a browser.
* Write an article to make clear all the advantages.
## License
[MIT licensed](LICENSE)