https://github.com/KanoComputing/routy.js
A dead simple browser module for hash routing
https://github.com/KanoComputing/routy.js
Last synced: about 1 year ago
JSON representation
A dead simple browser module for hash routing
- Host: GitHub
- URL: https://github.com/KanoComputing/routy.js
- Owner: KanoComputing
- License: mit
- Created: 2014-03-14T18:06:18.000Z (about 12 years ago)
- Default Branch: master
- Last Pushed: 2017-06-26T12:30:35.000Z (almost 9 years ago)
- Last Synced: 2025-03-30T12:33:39.443Z (about 1 year ago)
- Language: JavaScript
- Size: 38.1 KB
- Stars: 16
- Watchers: 19
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Routy.js
> A dead simple module to manage hash routing in the browser.
## Install
You can either use the module with npm
`npm install routy`
Or include the file `build/Routy.js` in your HTML (which provides a wrapper at `window.Routy`)
## Examples of usage
### Simple usage with controller functions
Bind functions to hashbang routes, execute them by changing the hash location to `#/path`.
```javascript
var Router = Require('routy').Router;
var myRouter = new Router();
function index (route, req) {
console.log(route); // The Route instance (containing path, custom options, ..)
console.log(req); // Will contained requested path, URL params, etc.. (If availabe, in different forms)
console.log(this); // The Router instance - also containing current `.path` and `.route`
}
function logParams (route, req) {
console.log(req.namedParams); // { apples: '..'}
}
function logOptions (route, req) {
// Access route custom options. Boom!
console.log(route.options); // { someOption: 'wooah' }
}
myRouter
.add('/', index)
.add('/foo/:apples', logParams)
.add('/bar', logOptions, { someOption: 'wooah' })
.on('change', function (req, route) {
console.log('Changing to path: ' + req.path);
});
```
### Extending routes
You can extend routes options by using the `id` and `extends` keys inside your route options object.
For example:
```javascript
myRouter
// This route will be extended
.add('/', {
id : 'parent-route',
foo : 'bar',
bar : 'foo'
})
// This route will also contain a `foo` option set to 'bar'
.add('/extended', {
extends : 'parent-root',
bar : 'foo'
})
```
### Simple templates example
`Routy.Router` instanciates as an event emitter.
Intercept the `change` event and access custom route options to render a template.
```javascript
var Router = require('routy').Router;
var router = new Router(),
view = document.getElementById('view');
// A full implementation would load templates from elsewhere
router
.add('/', { template: '
Main
' })
.add('/foo', { template: 'Foo
' })
.add('/bar', { template: 'Bar
' })
.otherwise('/')
.on('change', changeView);
function changeView (req) {
view.innerHTML = req.route.options.template;
}
router.run();
```
### Intercept route changes + redirect
You can intercept the `beforeChange` event to apply a redirect by setting a `.redirect` value on a `Routy.Router` instance.
```javascript
var Router = require('routy').Router;
var router = new Router(),
isLoggedIn = false;
router
.add('/')
.add('/private-view', { requiresLogin: true }) // Custom option
.add('/login')
.otherwise('/')
.on('beforeChange', intercept);
function intercept (req) {
if (req.route.options.requiresLogin) {
// Use the router.redirect property to redirect to a different path
router.redirect = '/login';
}
}
router.run();
```
### Intercept route changes + cancel
When intercepting `beforeChange` you can also just cancel route change before it happens by setting the `.cancel` property to true.
```javascript
var Router = require('routy').Router;
var router = new Router();
router
.add('/')
.add('/locked')
.otherwise('/')
.on('beforeChange', intercept);
function intercept (req) {
if (req.route.path === '/locked') {
// Use the router.cancel property to prevent redirection
router.cancel = true;
}
}
router.run();
```
### HTML5 mode
Hashbangs are not exactly the fanciest way of building routes in a one page app.
Activate HTML5 mode (Uses `history.pushState`) to have clean URL routes.
When the page is initialised they will parse the current `location.pathname` and execute on the appropriate route.
HTML5 mode will also listen for clicks on `` tags and replace the default behaviour of relative links.
```javascript
var Router = require('routy').Router;
var router = new Router();
router
.add('/')
.add('/foo')
.otherwise('/')
.html5()
.on('change', onChange);
function onChange (req) {
console.log(location.pathname);
// "/foo"
}
router.run();
```
## Router API
* `.add(route_pattern, [ route_function ], [ route_options ])` - Add a route with custom options and callback function
* `.otherwise(redirect_path)` - Set a default path string to redirect to when trying to access an undefined route
* `.run()` - Start listening to hash change events
* `.stop()` - Stop listening to hash change events
* `.refresh()` - Re-trigger route behaviour based on current path
* `.goTo(path)` - Direct to a given path
* `.html5([ state ])` - Pass a boolean (Defaults to `true`) to set / unset HTML5 mode
## Develop
1. Clone the repo and install the dependencies
```
git clone git@github.com:KanoComputing/routy.js.git
cd routy.js
npm install
```
2. Update the build
```
npm run build
```
## Licence
Copyright (c) 2014 Kano Computing Ltd. - Released under the [MIT license](https://github.com/KanoComputing/routy.js/blob/master/LICENSE)