jComponent / Helpers / Navigation for SPA
Updated: 09. February 2018
Author: Peter Širka

Navigation for Single Page Applications

Professional Support Chat with contributors

Navigation uses jRouting library, this library is designed for creating Single Page Applications. jComponent navigation uses two aliases to navigation:

Quick navigation:

Properties

// Contains the current URL address
NAV.url;

Methods

  • NAV.back()
  • NAV.clientside(selector)
  • NAV.middleware(name, fn)
  • NAV.refresh()
  • NAV.remove(url)
  • REDIRECT(url)
  • ROUTE(url, action, [middleware])

Method: NAV.back()

Method performs browser back operation.

NAV.back();
// returns {NAV}

Method: NAV.clientside()

Method watchs all links on the selector path. If the user click on the link then the method performs internal REDIRECT() - browser doesn't perform a classic redirect to server-side. This method will watch all links and the links can be created dynamically.

NAV.clientside(selector);
// @selector {String} jQuery selector
// returns {NAV}

NAV.clientside('a.routing');

Method: NAV.middleware()

Method registers a new middleware for routing. More info in Middleware's section bellow.

NAV.middleware(name, fn);
// @name {String} A middleware name
// @fn {Function(next)} Executor
// returns {NAV}

// or
MIDDLEWARE(name, fn);
// +v14.1.1

NAV.middleware('delay', function(next, options, roles) {
    // @next {Function} "next(false)" or "next(Error") won't be continue in processing
    // @options {Object} custom options defined in a route
    // @roles {String Array} roles defined in a route
    setTimeout(next, 1000);
});

Method: NAV.refresh()

Method performs refresh.

NAV.refresh();
// returns {NAV}

Method: NAV.remove()

Method removes registered routing.

NAV.remove(url);
// @url {String}
// returns {NAV}

NAV.remove('/');

Method: REDIRECT()

Method performs redirect without calling backend.

REDIRECT(url, [model]);
// @url {String} relative URL address
// @model {Object} custom model for this route

REDIRECT('/users/');

Method: ROUTE()

Method registers a new route. More info in Routing section bellow.

ROUTE(url, fn, [middleware], [init]);
// @url {String} relative URL address
// @fn {Function} executor
// @middleware {String Array} optional, can contain middleware + roles + options
// @init {Function} optional, init function is executed only the one time

ROUTE('/', function() {
    // action
}, ['middlewareA', 'middlewareB', '@role1', '@role2']);

Events

Global navigation events.

ON('location', function(url) {
    // URL address has been changed
});

ON('404', function(err) {
    // Route not found.
});

ON('500', function(err) {
    // Internal client-side error
});

Routing

Routing can be defined everywhere, but I recommend to create it in some client-side file like routes.js for clarity.

ROUTE('/', function() {
    // this action is executed if the URL will be "/"
});

ROUTE('/users/', function() {
    // this action is executed if the URL will be "/users/"
});

ROUTE('/products/{category}/', function(category) {
    // this action is executed if the URL will be "/products/SOMETHING/"
    console.log(category);
});

Middleware

Middleware can affect routing's action before is executed. So you can perform authorization or another operations in middleware, for example:

NAV.middleware('authorize', function(next, options, roles) {

    if (window.user)
        return next();

    // ...
    // sign-in
    window.user = user;
    next();

});

Custom options + roles in middleware:

ROUTE('/', function() {

    // some action

}, ['middleware', { name: 'Custom options' }, '@admin']);

NAV.middleware('middleware', function(next, options, roles) {

    console.log(options);
    // Output: { name: 'Custom options' }

    console.log(roles);
    // Output: admin

    next();
});

Custom errors in middleware:

NAV.middleware('error', function(next, options, roles) {

    if (someError) {    
        next(false); // or next(ErrorInstance)
        REDIRECT('/fallback/'); // or do something
        return;
    }

    next();

});

Good to know

How to read a value from URL address?

var query = MAIN.parseQuery();
// or
// var query = MAIN.parseQuery('q=Peter&age=30');

// ?q=Peter
console.log(query.q);
// Output: Peter

// ?age=30
console.log(query.age);
// Output: 30