router-base
v1.1.0
Published
javascript abstract, node.js and client-side router, inspired by symfony router
Downloads
163
Maintainers
Readme
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:
- node.js modules,
- requirejs modules
- and, of course, awesome ym modules.
- You can just use the
<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
- id - String, required. You can use it to link a route to your controller.
- path - String, required. Can include named parameters in
{parameterName}
form. - host - String, optional. Can include named parameters in
{parameterName}
form (For example, '{sub}.example.com'). - defaults - Object, optional. Keys are parameters names, values are parameters default values.
- requirements - Object, optional. You can use it to restrict parameters. Keys are parameters names, values are strings. Strings from values are for regular expressions, router uses it to test parameters.
- methods - Array, optional. For example,
['GET']
to allow onlyGET
methods. - schemes - Array, optional. For example,
['https']
to force https.
##RouterBase parameters
- routes - an Array of routes configs, the only required parameter
- defaultMethods - what methods available for routes,
['GET', 'POST', 'PUT', 'DELETE']
by default - defaultSchemes - what schemes available for routes,
['http', 'https']
by default - symbols.parametersDelimiters. By default,
.
and/
can be used as parameters delimiters in paths - symbols.parameterStart, default value is '{'
- symbols.parameterMatcher, default value is '.*?'
- symbols.parameterEnd, default value is '}'
##Where is tests?
Of course, in test
folder. Use npm test
to run.