Multifunctional JavaScript router solves the problem of routing your application, providing full control over the route.



Multifunctional JavaScript router solves the problem of routing your application, providing full control over the route. It can work either by itself or as a part of other framework, such as Backbone, in which it could be an excellent substitute for the standard Backbone.Router and even Backbone.View. Just try it.

Get started

Installation, testing, assembling

npm install pilotjs
cd pilotjs
npm install


  • options — parameter object, see an Example
var Ivan = new Pilot({
    el: null // container, which is used to intercept clicks
  , production: false  // this one is needed for switching off logging and error display

getUrl(id:String, params:Object[, extra:Object]):String

Get url by route id. You can use this method to construct url by route id and parameters without keeping links inside.

  • id — unique route identifier
  • params — parameters used to construct url
  • extra — additional parameters
var Ivan = new Pilot;

// Add route
Ivan.route('address', '/:city/(street/:id/)', function (evt, req){ });

Ivan.getUrl('address'); // return "/"
Ivan.getUrl('address', { city: 'berlin' }); // "/berlin/"
Ivan.getUrl('address', { city: 'berlin', id: 123 }); // "/berlin/street/10/"

go(id:String[, params:Object]):jQuery.Deffered

Navigation by the route id. It is often necessary not only to understand how user moved, but also to move user to the correct url, depending on his actions. This method allows you to change the route, operating with its id and parameters only.

  • id — unique route identifier
  • params — parameters used to construct url
var Ivan = new Pilot;

Ivan.route('coordinates', '/coordinates/:lat/:long', function (evt, req){ });

Ivan.go('coordinates', { lat: 16 }); // location: "/coordinates/16/"
Ivan.go('coordinates', { lat: 16, long: 178 }); // location: "/coordinates/16/178/"

nav(url:String[, force:Boolean]):jQuery.Deffered

Navigation by url. With the call of this method, router finds all the handlers for this route and goes to it. If url has not been changed, the transition will not be executed, but you can get round it using force parameter.

  • url — relative or absolute url
  • force — force the user to move to the url even if he's already on it
var Ivan = new Pilot
            .on('beforeroute', function (req){  })
            .on('route', function (req){  })
            .on('404', function (req){ console.log('Route not found'); })
            .route('/base/moscow/', function (evt, req){
            	console.log('Greetings from Moscow');

Ivan.nav('/base/moscow/'); // "Greetings from Moscow"
Ivan.nav('/base/moon/'); // "Route not found"


Start router. When called with no parameters, the initial url is obtained through Pilot.getLocation.

  • url — initial routing point

route(pattern:String, handler:Function[, withEndEvent:Boolean]):Pilot

A simple way to add a route.

  • pattern — used for matching request while navigation
  • handler — called with event and request parameters, if pattern matched with url
  • withEndEvent — calls handler in the end of route
// Without "routeend"
Ivan.route('/airport/', function (evt, req){
    console.log(evt.type, '-> ', req.path);

// With "routeend"
Ivan.route('/:city/(street/:id/)', function (evt, req){
    if( evt.type == 'routeend' ){
        console.log(evt.type, '-> ', req.referrer.path);
    } else {
        console.log(evt.type, '-> ', req.params.city, ', ', req.params.id);
}, true);

Ivan.nav('/airport/');        // "routestart -> /airport/"
Ivan.nav('/home/street/123'); // "routestart -> home, 123"
Ivan.nav('/home/street/321'); // "routechange -> home, 321"
Ivan.nav('/airport/');        // "routestart -> /airport/"
                              // "routeend -> /home/street/321/"

route(id:String, pattern:String, handler:Function[, withEndEvent:Boolean]):Pilot

A simple way to add a named route.

  • id — unique route identifier
  • other parameters
Ivan.route('base', '/base/:lat/:long');

// Navigate by id
Ivan.go('base', { lat: 16, lon: 179 }); // location: /base/16/179

route(pattern:String, ctrl:Object|Pilot.Route[, options:Object]):Pilot

Add a route controller. Route controller is a powerful tool. With its help one you can tell the router (passing Deffered parameter), that it ought to wait for the receipt of data and only then make the move to the route. This approach works well in combination with multiple controllers on one route, where each one performs its small task, e.g., the first one gets a banner, the second one get list of posts, and the third one gets user profile.

  • ctrl — controller methods or successor Pilot.Route
  • options — initialization options
Ivan.route('/base/:id', {
    loadData: function (req){
        return $.ajax('/base/get/'+req.params.id, function (base){
    onRoute: function (evt, req){
        // "routestart" and "routeend"
        var base = this.getData();
        console.log('route:', base.name);

Ivan.nav('/base/123'); // "route: Kienitz"

route(id:String, pattern:String, ctrl:Object|Pilot.Route[, options:Object]):Pilot

Add a named route controller.

var airport = Pilot.Route.extend({
    onRoute: function (){
        console.log('base:', this.getData().name);

    .route('/base/1', airport, { data: { name: 'Moscow' } })
    .route('/base/2', airport, { data: { name: 'Yaroslavl' } })

Ivan.nav('/base/1'); // "base: Moscow"
Ivan.nav('/base/2'); // "base: Yaroslavl"


Create a group and assign routes relative to it.

  • pattern — base pattern
var Ivan = new Pilot;
                .route('.', function (evt, req){ console.log('def'); })
                .route(':id', function (evt, req){
                	console.log('base: '+.req.params.id);

Ivan.nav('/base/'); // "def"
Ivan.nav('/base/123/'); // "base: 123"

createGroup(id:String, pattern:String):Pilot

Create a named group

  • id — unique route identifier


Close the group and return the last one or router.

on(events:String, fn:Function):Pilot

Add a handler for one or more events. Pilot has four events: beforeroute, route, 404 и error

  • events — one or more events, namespace can be used
  • fn — handler function
new Pilot
	.on('beforeroute', function (evt/**$.Event*/, req/**Pilot.Request*/){ })
	.on('route', function (evt/**$.Event*/, req/**Pilot.Request*/){ })
	.on('404', function (evt/**$.Event*/, req/**Pilot.Request*/){ })
	.on('error', function (evt/**$.Event*/, err/**Error*/){ })

off(events:String, fn:Function):Pilot

Switch off event handler.

  • events — one or more events, namespace can be used
  • fn — handler function
new Pilot
	// Subscribe
	.on('route.one', function (evt/**$.Event*/, req/**Pilot.Request*/){
		// Unsubscribe using namespace

emit(event:String[, args:Array]):Pilot

Emit event.

  • event — event name
  • args — extra arguments
var Ace = new Pilot
	.on('custom', function (evt/**$.Event*/, foo/**String*/){  })

// Emit event
Ace.emit('custom', ["foo"]);


Browsing history, the behavior is similar to window.history.

var Ace = new Pilot;

// etc

// ["http://site.com/airport/", "http://site.com/airport/depot/", ..]


Verify that you can go back through history


Verify that you can go forward through history


Go to the previous url in history


Go to the next url relative to the current position in history


This class of the route controller allows not only to control events of starting, changing or ending of the route, but also to inform the router that before going to the correct url it has to wait the collection of data necessary to this controller.


Available events: routestart, routechange and routeend. There is also route event, which is similar to routestart and routechange.

var airbase = Pilot.Route.extend({
	init: function (){
		this.on('routestart routeend', function (evt/**$.Event*/, req/**Pilot.Request*/){
			// ...

	onRoute: function (evt/**$.Event*/, req/**Pilot.Request*/){
		// You can also define a method with the name of the event


Additional rules test parameters

Ivan.route("/just/:name/", {
	paramsRules: {
		name: function (value/**String*/, req/**Pilot.Request*/){
			return value == "moscow" || value == "kiev";


Pilot.access['denied'] = function (req/**Pilot.Request*/){
	return	false;

var Spy = new Pilot;

Spy.route('/public/', function (){ console.log("Public!"); })

Spy.route('/private/', {
	accessPermission: 'denied', // permission
	accessDeniedRedirectTo: '/public/'

Spy.route('/public/closed/', {
	accessPermission: 'denied', // permission
	accessDeniedRedirectTo: '..'

Spy.nav('/private/'); // "Public!"
Spy.nav('/public/closed/'); // "Public!"


Adopt such values ​​as: url, route id, function or .. to rise to a up level.

var ClosedBase = Pilot.Route.extend({
	accessPermission: false,
	accessDeniedRedirectTo: function (req/**Pilot.Request*/){
		return	this.router.getUrl('home');


Route initialization flag.

var airbase = Pilot.Route.extend({
	loadData: function (){
		if( !this.inited ){
			this.setData({ name: 'Ramstein' });


Link to the router.


List of methods that will be executed in the context of the object. It's very convenient for using with functions which will be used as event handlers.

var City = Pilot.Route.extend({
    name: 'Moscow',
    boundAll: ['matryoshka', 'vodka', 'balalaika'],
    init: function (){
    matryoshka: function (evt){ console.log(this.city+': take ', evt) },
    vodka: function (evt){ console.log(this.city+': drink ', evt) },
    balalaika: function (evt){ console.log(this.city+': play ', evt) },


Bound the method with the context of the controller.

  • fn — function or its name in the controller
var airport = Pilot.View.extend({
    el: '#airport',
    init: function (){
        // Bound function
        this.$el.on('mouseenter', this.bound(function (evt){
        // Bound by method name
        this.$el.on('mouseleave', this.bound('_onHover'));
    _onHover: function (evt){
        this.$el.toggleClass('hovered', evt.type == 'mouseenter');


This method is intended to redefine and should be called once at the time of initialization of the controller. Remember that the initialization is not involved in creating the instance, that occurs in the first call of the controller after loadData, but before the routestart event.

var airport = Pilot.Route.extend({
    init: function (){
        this.$el = $('#airport');


This method should be called before routestart, routechange. If $.Deffered returns, router will wait for the end of the controller data collection and then execute the navigation.

  • req — request object
var airport = Pilot.Route.extend({
    loadData: function (req){
        return $.ajax('/load/data/', req.query, this.bound(function (data){
            this.setData( data );
    onRoute: function (){
        var data = this.getData();

getUrl(id:String, params:Object[, extra:Object]):String

Get url by route id. You can use this method to construct url by route id and parameters without keeping links inside.

  • id — unique route identifier
  • params — parameters used to construct url
  • extra — additional parameters


A simple method to get controller data.

var airport = Pilot.Route.extend({
    data: { name: 'default' }

(new airport).getData().name; // "default"
(new airport({ data: { name: 'NY' } })).getData().name; // "NY"

setData(data:Object[, merge:Boolean]):Pilot.Route

Set new controller data or merge with the current ones.

  • data — new data
  • merge — merge with the current ones
var airport = Pilot.Route.extend({
    data: { name: 'default', city: 'unknown' }

(new airport).setData({ name: 'Foo' }).getData();
// { name: 'Foo' }

(new airport).setData({ name: 'Foo' }, true).getData();
// { name: 'Foo', city: 'unknown' }

(new airport).setData({ name: 'Foo', city: 'Bar' }).getData();
// { name: 'Foo', city: 'Bar' }


Pilot.Route successor implements methods for working with DOM elements, events and patterning. By default, Pilot.View is subscribed to routestart and routeend events and controls the visibility of a DOM element associated with it, setting it to display: none or removing it.


Link to the DOM element, with which View is working.

var airport = Pilot.View.extend({
    el: '#airport-default'

(new airport).el; // HTMLElement: <div id="airport-default">..</div>
(new airport({ el: '#moscow' })).el; // HTMLElement: <div id="moscow">..</div>


jQuery collection, for more convenient work.

var base = Pilot.View.extend({
    el: '#moscow'

(new base).el; // jQuery[<div id="moscow">..</div>]
(new base({ el: '#moon' })).el; // jQuery[<div id="moon">..</div>]


If you specify this option, this tag will be created while the initialization.

var base = Pilot.View.extend({
    tagName: 'span'

(new base).el; // HTMLElement: <span>..</span>
(new base).$el.appendTo('body'); // jQuery[<span>..</span>]


Create a tag and put it in the container.

var base = Pilot.View.extend({
    tag: '#box span.base.base_military'

(new base).el; // HTMLElement: <span class="base base_military">..</span>


var airbase = Pilot.View.extend({
	el: '#aribase',
	sigleton: true,
	onRouteStart: function (evt, req){
		console.log('start:', req.path);
	onRouteChange: function (evt, req){
		console.log('change:', req.path);
	onRouteStart: function (evt, req){
		console.log('end:', req.path);

var Ivan = new Pilot
	.route('/sky/foo/', airbase)
	.route('/sky/bar/', airbase)
	.route('/sky/baz/', function (evt, req){
		console.log('Sky base Baz');
	.route('/sky/qux/', airbase)

Ivan.nav('/sky/foo/'); // "start: /sky/foo/"
Ivan.nav('/sky/bar/'); // "change: /sky/bar/"
Ivan.nav('/sky/qux/'); // "change: /sky/qux/"
Ivan.nav('/sky/baz/'); // "Sky base Baz"
                       // "end: /sky/baz/"


Here can be any patterning function.

var region = Pilot.View.extend({
    template: function (data/**Object*/){
    	/* "data" is equal this.getData() */
    	// Use any template engine
    	return	xtpl.fetch('templates/region.xtpl', data);


This method is called at the start and in the end of the route. Its redefining can help you change the way elements are displayed, e.g., to add the animation.

  • state — true: route start, false: route end
var region = Pilot.View.extend({
    toggleView: function (state/**Boolean*/){
    	this.$el.animate({ opacity: +state }, 'fast');


Set the element with which 'View' is working (automatically changes this.el and this.$el properties).

  • selector - string containing jQuery selector or HTMLElement, detail


Select elements inside the 'View' (equal to this.$el.find, but more easy).

  • selector - string containing jQuery selector or HTMLElement, detail


Get HTML based on this.template and sent data or 'View' data.

  • data — data for patterning


Refresh HTML this.el by this.getHtml()

var city = Pilot.View.extend({
	templateFile: 'city/default.xtpl',
	template: function (obj){
		return xtpl.fetch(this.templateFile, obj);
	onRoute: function (){

<a name="Pattern-syntax>

Pattern-syntax route

  • `/search/` — strict match
  • `/gallery/:tag/` — parameterized
  • `/search/result/:page?` — parameterized (optional)
  • `/user/:id(\\d+)` — parameter validation
  • `/search/(result/:page/)?` — grouping


route: /gallery/:tag/:perPage?(/page/:page)?
request: /gallery/cubism/20/page/123?search=text


Add and use its methods, eg:

Pilot.Request.fn.getPage = function (){
	return	parseInt(this.params.page || this.query.page, 10) || 1;

(new Pilot)
	.route('/news/page/:page', function (evt, req/**Pilot.Request*/){
		var page = req.getPage();
		console.log('news.page:', page);
	.route('/search/', function (evt, req/**Pilot.Request*/){
		var page = req.getPage();
		console.log('search.page:', page);
	.nav('/news/page/') // news.page: 1
	.nav('/news/page/2/') // news.page: 2
	.nav('/search/?page=123') // search.page: 123


Absolute url: http://domain.com/gallery/cubism/20/page/3?search=text


The path relative to the web-site root: /gallery/cubism/20/page/3


GET parameters string: ?search=text


GET parameters object: { search: "text" }


Route parameters: { tag: "cubism", perPage: 20, page: 123 }


Contains url of previous request: http://domain.com/gallery/cubism/20/page/12


Check the current route

  • id — id routes, separated by a space

getUrl(id:String[, params:Object]):Boolean

Check the current route

  • id — route id
  • params — route parameters


Clone method.

History API

By default, the library doesn't contain any polyfills and rely only on native support.


Use the full History API, otherwise location.hash.

Pilot.pushState = true;


Get current location.


Set a new location.

  • req — request object



  • Event hashchange does not listen, if Router.pushState is true


  • Removed depending on jQuery
  • + Support for alternative: `Deferred` & `Emitter`
  • (!!) `emit` -> `trigger` (!!)
  • + `Pilot.Route.fn.setTemplate(fn)`
  • + Pilot.Request.fn.is(id)
  • * Pilot.Request: micro bug fixes
  • * JSDoc


  • + Pilot.create
  • + `Pilot.View.fn.toggleEffect: "toggle"` and `Pilot.View.toggleEffect(name, fn)`
  • + `Pilot.Route.fn.loadDataOnce(req)`, `Pilot.Route.fn.setLoadedData(data)` and `Pilot.Route.fn.getLoadedData()`
  • + `Pilot.Route.fn.setRouteError()`
  • + `tap` event


  • + `profile` option
  • + `subroutes` & `subviews`
  • * catch errors
  • + grunt-version task


  • + `paramsRules` route option
  • + `accessPermission` route option
  • + `accessDeniedRedirectTo` route option


  • + Support Zepto, Ender or $
  • Fixed set request params
  • Fixed Pilot options


  • [#4](https://github.com/RubaXa/Pilot/pull/4): Added Pilot.Request.
  • + Pilot.utils.each
  • + Pilot.utils.extend
  • + Pilot.utils.qs.parse(queryString)`:Object`
  • + Pilot.utils.qs.stringify(queryObject)`:String`



First release