pilotjs

Multifunction JavaScript router.

npm install pilotjs
2 downloads in the last day
9 downloads in the last week
28 downloads in the last month

Pilot

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

  • Gallery: jQuery + FlickrAPI (step by step)

Installation, testing, assembling

npm install pilotjs
cd pilotjs
npm install
grunt


constructor([options:Object]):void

  • 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/"

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([url:String]):void

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.

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){
            this.setData(base);
        }.bind(this));
    },
    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);
    }
});

Ivan
    .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"

createGroup(pattern:String):Pilot

Create a group and assign routes relative to it.

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

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

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

Create a named group

  • id — unique route identifier

closeGroup():Pilot

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
        this.off('.one');
    })
;

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"]);

history:Array

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

var Ace = new Pilot;

Ace.nav('/airport/');
Ace.nav('/airport/depot/');
// etc

console.log(Ace.history);
// ["http://site.com/airport/", "http://site.com/airport/depot/", ..]

hasBack():Boolean

Verify that you can go back through history


hasForward():Boolean

Verify that you can go forward through history


back():jQuery.Deffered

Go to the previous url in history


forward():jQuery.Deffered

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


Pilot.Route

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.


@events

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
    }
});

paramsRules:Object

Additional rules test parameters

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

accessPermission:String

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!"

accessDeniedRedirectTo:String

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');
    }
});

inited:Boolean

Route initialization flag.

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

router:Pilot

Link to the router.


boundAll:Array

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 (){
        $('#take').click(this.matryoshka);
        $('#drink').click(this.vodka);
        $('#play').click(this.balalaika);
    },
    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(fn:String|Function):Function

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){
            this._onHover(evt);
        }));

        // Bound by method name
        this.$el.on('mouseleave', this.bound('_onHover'));
    },
    _onHover: function (evt){
        this.$el.toggleClass('hovered', evt.type == 'mouseenter');
    }
});

init():void

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');
    }
});

loadData(req:Pilot.Request):jQuery.Deffered|Null

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

getData():Object

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.View

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.


el:HTMLElement

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>

$el:jQuery

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>]

tagName:String

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>]

tag:String

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>

singleton:Boolean

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/"

template:Fucntion

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);
    }
});

toggleView(state:Boolean):void

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');
    }
});

setElement(selector:jQuerySelector):Pilot.View

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

  • selector - string containing jQuery selector or HTMLElement, detail

$(selector:jQuerySelector):jQuery

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

  • selector - string containing jQuery selector or HTMLElement, detail

getHtml([data:Object]):String

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

  • data — data for patterning

render():void

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 (){
        this.render();
    }
});

<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

Pilot.Request

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

@extend

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
;

url:String

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

path:String

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

search:String

GET parameters string: ?search=text

query:Object

GET parameters object: { search: "text" }

params:Object

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

referrer:String

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

is(id:String):Boolean

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():Pilot.Request

Clone method.


History API

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

Pilot.pushState:Boolean

Use the full History API, otherwise location.hash.

Pilot.pushState = true;

Pilot.getLocation():String

Get current location.

Pilot.setLocation(req:Object):void

Set a new location.

  • req — request object

Changelog

1.6.0

  • 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

1.5.0

  • + 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

1.4.0

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

1.3.0

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

1.2.1

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

1.2.0

  • #4: Added Pilot.Request.
  • + Pilot.utils.each
  • + Pilot.utils.extend
  • + Pilot.utils.qs.parse(queryString):Object
  • + Pilot.utils.qs.stringify(queryObject):String

1.1.0

  • #3: Allow customize selector for links.

1.0.0

First release

npm loves you