Grapnel
The first (started in 2010!) Client/Server-Side JavaScript Router with Named Parameters, HTML5 pushState, and Middleware support.
Download/Installation
Download Source:
Install with npm
npm install grapnel
Or by using bower:
bower install grapnel
Server only: (with HTTP methods added, more info)
npm install grapnel-server
Grapnel Features
- Supports routing using
pushState
or hashchange
concurrently - Supports Named Parameters similar to Express, Sinatra, and Restify
- Middleware Support
- Works on the client or server side
- RegExp Support
- Supports
#
or #!
for hashchange
routing - Unobtrusive, supports multiple routers on the same page
- No dependencies
Basic Router
const router = new Grapnel();
router.get('products/:category/:id?', function(req) {
let id = req.params.id;
let category = req.params.category;
console.log(category, id);
});
Using HTML5 pushState
const router = new Grapnel({ pushState : true });
router.get('/products/:category/:id?', function(req) {
let id = req.params.id;
let category = req.params.category;
console.log(category, id);
});
router.navigate('/products/widgets/134');
Named Parameters
Grapnel supports regex style routes similar to Sinatra, Restify, and Express. The properties are mapped to the parameters in the request.
router.get('products/:id?', function(req) {
console.log(req.params.id);
});
router.get('products/*', function(req) {
});
Middleware Support
Grapnel also supports middleware:
let auth = function(req, event, next) {
user.auth(function(err) {
req.user = this;
next();
});
}
router.get('/*', auth, function(req) {
console.log(req.user);
});
Route Context
You can add context to a route and even use it with middleware:
let usersRoute = router.context('/user/:id', getUser, getFollowers);
usersRoute('/', function(req, event) {
console.log('Profile', req.params.id);
});
usersRoute('/followers', otherMiddleware, function(req, event) {
console.log('Followers', req.params.id);
});
router.navigate('/user/13589');
router.navigate('/user/13589/followers');
Works as a server-side router
import { createServer } from 'http';
import Grapnel from 'grapnel';
const app = new Grapnel();
app.get('/', function(req, route) {
route.res.end('Hello World!', 200);
});
createServer(function(req, res) {
app.once('match', function(route) {
route.res = res;
}).navigate(req.url);
}).listen(3000);
This is now simplified as a separate package (more info)
npm install grapnel-server
Declaring Multiple Routes
let routes = {
'products' : function(req) {
},
'products/:category/:id?' : function(req) {
console.log(req.params.category);
}
}
Grapnel.listen(routes);
Event Handling
const router = new Grapnel({ pushState : true, root : '/' });
router.on('navigate', function(event){
console.log('URL changed to %s', this.path());
});
RegExp Support
Grapnel allows RegEx when defining a route:
const router = new Grapnel();
let expression = /^food\/tacos\/(.*)$/i;
router.get(expression, function(req, event){
console.log('I think tacos are %s.', req.params[0]);
});
Usage & Tips
Basic Configuration
const router = new Grapnel();
Enabling PushState
const router = new Grapnel({ pushState : true });
You can also specify a root URL by setting it as an option:
const router = new Grapnel({ root : '/app', pushState : true });
The root may require a beginning slash and a trailing slash depending on how you set up your routes.
Middleware
Grapnel uses middleware similar to how Express uses middleware. Middleware has access to the req
object, route
object, and the next middleware in the call stack (commonly denoted as next
). Middleware must call next()
to pass control to the next middleware, otherwise the router will stop.
For more information about how middleware works, see Using Middleware.
let user = function(req, route, next) {
user.get(function(err) {
req.user = this;
next();
});
}
router.get('/user/*', user, function(req) {
console.log(req.user);
});
Declaring your routes with an object literal:
Grapnel.listen({
'products/:id' : function(req) {
}
});
When declaring routes with a literal object, router options can be passed as the first parameter:
let opts = { pushState : true };
Grapnel.listen(opts, routes);
Navigation
If pushState is enabled, you can navigate through your application with router.navigate
:
router.navigate('/products/123');
Stopping a Route Event
router.on('match', function(routeEvent) {
routeEvent.preventDefault();
});
Stopping Event Propagation
router.get('/products/:id', function(req, routeEvent) {
routeEvent.stopPropagation();
});
router.get('/products/widgets', function(req, routeEvent) {
});
router.navigate('/products/widgets');
404 Pages
You can specify a route that only uses a wildcard *
as your final route, then use route.parent()
which returns false
if the call stack doesn't have any other routes to run.
let routes = {
'/' : function(req, route) {
},
'/store/products/:id' : function(req, route) {
},
'/category/:id' : function(req, route) {
},
'/*' : function(req, route) {
if(!route.parent()){
}
}
}
Grapnel.listen({ pushState : true }, routes);
Setting window state
router.navigate('/', {
state: { ...windowState }
});
Documentation
get
Adds a listeners and middleware for routes
router.get('/store/:category/:id?', function(req, route){
let category = req.params.category;
let id = req.params.id;
console.log('Product #%s in %s', id, category);
});
navigate
Navigate through application
router.navigate('/products/123', ...options);
on
Adds a new event listener
router.on('myevent', function(event) {
console.log('Grapnel works!');
});
once
A version of on
except its handler will only be called once
router.once('init', function() {
console.log('This will only be executed once');
});
emit
Triggers an event
router.emit('event', eventArg1, eventArg2, ...etc);
context
Returns a function that can be called with a specific route in context.
Both the router.context
method and the function it returns can accept middleware. Note: when calling route.context
, you should omit the trailing slash.
let usersRoute = router.context('/user/:id');
usersRoute('/followers', function(req, route) {
console.log('Followers', req.params.id);
});
router.navigate('/user/13589/followers');
path
router.path('string')
Sets a new path or hashrouter.path()
Gets path or hashrouter.path(false)
Clears the path or hash
bind
An alias of on
trigger
An alias of emit
add
An alias of get
Options
pushState
Enable pushState, allowing manipulation of browser history instead of using the #
and hashchange
eventroot
Root of your app, all navigation will be relative to thistarget
Target object where the router will apply its changes (default: window
)hashBang
Enable #!
as the anchor of a hashchange
router instead of using just a #
Events
navigate
Fires when router navigates through historymatch
Fires when a new match is found, but before the handler is calledhashchange
Fires when hashtag is changed
License