Base router for your JS framework or frameworkless app
MIT License
Base router for your JS framework or frameworkless app
It's abstract and knows nothing about http. It's just matches and generates urls.
##How to include it in my app or framework?
Router supports:
<script>
tag also, RouterBase will export the global variable then.You can install it with npm:
$ npm install router-base
or bower:
$ bower install router-base
##How to use it?
###Very basic example
At first, you need to create an instance:
var myRouter = new RouterBase({
routes: myRoutes // routes config
});
Where routes config is an Array with objects, each object is a configuration for a route. For example:
var myRoutes = [{
id: 'simplest_route',
path: '/a/route'
}];
var myRouter = new RouterBase({
routes: myRoutes
});
// You can generate routes by id:
myRouter.generate('simplest_route');
// returns '/a/route'
// You can find a route by path and method:
myRouter.match({path: '/a/route', method: 'GET'});
// returns {id: 'simplest_route', parameters: {}, definition: { id: 'simplest_route',
path: '/a/route',
defaults: {},
requirements: {},
host: undefined,
methods: [ 'GET', 'POST', 'PUT', 'DELETE' ],
schemes: [ 'http', 'https' ] } }
}
// You can get full info about a route by id:
myRouter.getRouteInfo('simplest_route');
// for answer see [tests](https://github.com/apsavin/router-base/blob/master/test/data/getRouteInfo-data.js#L4-L41)
You can use access to the definition
if you want to set additional fields to the route.
For example, you can mark route as secure specifying secure: true
in the route config
and then check this field like this:
var route = myRouter.match({path: '/a/route', method: 'GET'});
if (route && route.definition.secure) // do something
I will omit the definition
field in the next examples.
###Beautiful urls examples
####You can use named parameters in paths of the routes.
var myRoutes = [{
id: 'route_with_parameter_in_path',
path: '/some/path/{parameter}'
}];
myRouter.generate('route_with_parameter_in_path');
// will throw an Error, because parameter is needed for the route
myRouter.generate('route_with_parameter_in_path', {parameter: 1});
// returns '/some/path/1'
myRouter.generate('route_with_parameter_in_path', {parameter: 'value'});
// returns '/some/path/value'
myRouter.match({path: '/some/path/', method: 'GET'});
// returns null
myRouter.match({path: '/some/path/to', method: 'GET'});
// returns {id: 'route_with_parameter_in_path', parameters: {parameter: 'to'}, definition: {...}}
####Optional parameters in paths
var myRoutes = [{
id: 'route_with_parameter_in_path',
path: '/some/path/{parameter}',
defaults: {parameter: 1}
}];
myRouter.generate('route_with_parameter_in_path');
// returns '/some/path'
myRouter.generate('route_with_parameter_in_path', {parameter: 1});
// returns '/some/path/1'
myRouter.generate('route_with_parameter_in_path', {parameter: 'value'});
// returns '/some/path/value'
myRouter.match({path: '/some/path', method: 'GET'});
// returns {id: 'route_with_parameter_in_path', parameters: {parameter: 1}, definition: {...}}
myRouter.match({path: '/some/path/to', method: 'GET'});
// returns {id: 'route_with_parameter_in_path', parameters: {parameter: 'to'}, definition: {...}}
####Restricted parameters in paths
var myRoutes = [{
id: 'route_with_parameter_in_path',
path: '/some/path/{parameter}',
defaults: {parameter: 1},
requirements: {parameter: '\\d+'}
}];
myRouter.generate('route_with_parameter_in_path');
// returns '/some/path'
myRouter.generate('route_with_parameter_in_path', {parameter: 1});
// returns '/some/path/1'
myRouter.generate('route_with_parameter_in_path', {parameter: 'value'});
// throws an Error, because parameter is not numeric
myRouter.match({path: '/some/path', method: 'GET'});
// returns {id: 'route_with_parameter_in_path', parameters: {parameter: 1}, definition: {...}}
myRouter.match({path: '/some/path/to', method: 'GET'});
// returns null
##All possible routes parameters
{parameterName}
form.{parameterName}
form (For example, '{sub}.example.com').['GET']
to allow only GET
methods.['https']
to force https.##RouterBase parameters
['GET', 'POST', 'PUT', 'DELETE']
by default['http', 'https']
by default.
and /
can be used as parameters delimiters in paths##Where is tests?
Of course, in test
folder. Use npm test
to run.