jq-router

v4.6.1

Published

2 years ago

A tiny jQuery plugin for building single page application (SPA) with the possibility of nested views

Downloads

jQ-Router($.router)

Built on jQuery 1.3.0 & Inspried by (Angular ui-router & jQuery Single Page Application micro framework).

Features

Tiny
Pure jQuery based Single Page Application (SPA)
State based routing
Seperation Concerns
Nested Views
Events
Supports Navigation via both href & javascript

Demo

Simple
- Easy & Simple
Simple-Non-Cache
- Easy & Simple
- Cachable Routes
Nested Views
- Nested View (Parent > Child > Grand Child)
Lazy Store
- Nested View
- View Model
- Accessing Params
- Generating Urls (via $.router.href)
Admin Portal
- Deferred Execution of Route(via resolve)
- Redirection (via $.router.go)
Gallery
- Accessing Params
- Nested Views
- Abstract Views

Installation

Manual Installation

Download the jq-router.js file or jq-router.min.js (recommended) file from dist folder and include it in your page either in the <head> section or just before the closing tag of the <body> section after including jquery library.

NPM

> npm install jq-router

Bower

$ bower install jq-router

Introduction

A tiny jQuery plugin for building single page application (SPA) with the possibility of nested views.

Basic Example

(function () {
   var routes = {},
	defaultRoute = 'home';

    routes['home'] = {
	url: '#/',
	templateUrl: 'templates/home.html'
    };

    routes['contact'] = {
	url: '#/contact',
	templateUrl: 'templates/contact.html'
    };

    $.router
	.setData(routes)
	.setDefault(defaultRoute);

    $.when($.ready)
	.then(function() {
	    $.router.run('.my-view','home');
	});
}());

Documentation

Routes is collection of route objects. Each route object consists of url, templateUrl & each route can be parent route of another route.

    var routes = {};
    
    route["parent"] = {
	url: '', 
	abstract: true,
	templateUrl: ''
    }
    
    route["parent.child"] = {
	url: '', 
	templateUrl: ''
    }
    
    route["parent.child.grandchild"] = {
	url: '', 
	cache: bool,
	templateUrl: ''
    }

Details description of route properties

abstract: true

if route has child route & view

url: ''

Should be hashed('#') url that can contain accept optional parameters using (:name)

templateUrl: ''

Allowing caching of route template or you can also set default to all routes in setData,

cahce: true || false

Path to render the view in matched view selector.

resolve: callback //function or [] of function

A callback function or array of function's which is executed when a route is matched & route is rendered only when all deferred objects are resolved.s

 $.router.setData(data, isCacheTempalte);

setDate takes two parameters

data: A route object which contains route definition, like url, template url, route is parent & should it be cached.
isCacheTempalte: If the templates are server side pages (like php, aspx, jsp, or server rendered). Then you set this to false & templates are not cached.

 $.router.setDefault(name);

setDefault

name: A route name, if the url does not match to any route, router will redirect to default secified route.

$.when($.ready)
  .then(function() {
	$.router.run('.ui-view', 'home');
  });

Run takes two parameters

View selector, This will be used to match element & replace the template.
On Initial load, Navigate to a route.

Events

There are about 6 events, you can listen to these events or subscribe to events via router. Events are triggered in the following order.

Event Trigger Order

If Route Matched:

	onRouteMatched -> onRouteBeforeChange -> onViewDestroyed -> onViewChange -> onRouteChanged

If Route Not Matched:

	onRouteNotMatched

This event is trigged when view is loaded in to dom & either controller or viewmodel can be initiated.

Window Event
View Route
Matched Route
Matched Params

$(window).trigger($.router.renderViewSuccess, function(e, viewRoute, route, params){
	// ...
});

//or

$(window).trigger('jqRouter.renderViewSuccess', function(e, viewRoute, route, params){
	// ...
});

//or

$.router.onViewChange( function(e, viewRoute, route, params){
	// ...
});

This event is trigged when before current route is changed.

Window Event
Matched Route
Matched Params

$(window).trigger($.router.routeChangeStart, function(e, route, params){
	// ...
});

//or

$(window).trigger('jqRouter.routeChangeStart', function(e, route, params){
	// ...
});

//or

$.router.onRouteBeforeChange( function(e, route, params){
	// ...
});

This event is trigged when current route is changed.

Window Event
Current Route
Current Params

$(window).trigger($.router.routeChangeSuccess, function(e, route, params){
	// ...
});

//or

$(window).trigger('jqRouter.routeChangeSuccess', function(e, route, params){
	// ...
});

//or

$.router.onRouteChanged( function(e, route, params){
	// ...
});

This event is trigged when a route is matched.

Window Event
Matched Route
Matched Params

$(window).trigger($.router.routeMatched, function(e, route, params){
	// ...
});

//or

$(window).trigger('jqRouter.routeMatched', function(e, route, params){
	// ...
});

//or

$.router.onRouteMatched( function(e, route, params){
	// ...
});

This event is trigged when a route is not matched.

Window Event
Matched Route
Matched Params

$(window).trigger($.router.routeNotMatched, function(e, route, params){
	// ...
});

//or

$(window).trigger('jqRouter.routeNotMatched', function(e, route, params){
	// ...
});

//or

$.router.onRouteNotMatched( function(e, route, params){
	// ...
});

This event is trigged when view unloaded from dom. In a nested view they will be trigged from bottom to top last route that is getting changed

Window Event
View Route

$(window).trigger($.router.viewDestroyed, function(e, viewRoute){
	// ...
});

//or

$(window).trigger('jqRouter.viewDestroyed', function(e, viewRoute){
	// ...
});

//or

$.router.onViewDestroyed( function(e, viewRoute){
	// ...
});