pager.js is a JavaScript library based on KnockoutJS, jQuery and Underscore.js that provides the possibility of creating single page applications in a declarative fashion

• nesting subpages inside subpages where each subpage can be developed standalone but still communicate between each other.

This makes it easier to design very large scale single page web sites.

See the demo.

1. Download the developer version, the minified version, the AMD version, the AMD jQuery hashchange version, or the AMD History.js version of pager.js

2. Include all dependencies (jQuery, Underscore.js/Lo-Dash, KnockoutJS) as well as pager.js in your site using either AMD or non-AMD:

    // AMD
    requirejs.config({
        paths:{
            jquery:'jquery-1.8.2.min',
            underscore:'lodash.min',
            knockout:'knockout-2.1.0',
            pager:'pager.amd.min',
            // iff using jquery hashchange
            hashchange:'jquery.ba-hashchange.min',
            // iff using History.js
            history: 'jquery.history'
        }
    });
   
    // non-AMD
    <script type="text/javascript" src="jquery-1.8.2.min.js"></script>
    <script type="text/javascript" src="underscore-min.js"></script>
    <script type="text/javascript" src="knockout-2.1.0.js"></script>
    <script type="text/javascript" src="pager.js"></script>
   

3. Insert the lines:

    pager.extendWithPage(viewModel);
    ko.applyBindings(viewModel);
    pager.start();
   

4. Start using the bindings page and page-href. Consult the web page, demo or test cases for how to use the bindings.

5. Rock 'n' Roll!

• KnockoutJS
• jQuery
• Underscore.js or Lo-Dash

You will usually use pager.js in combination with either jQuery hashchange or History.js.

pager.js is not depending on any CSS framework!

For developing pager.js you'll also need

• Node.js
• Grunt
• QUnit
• PhantomJS
• RequireJS

Developing a huge single page application should be like developing multiple small pages. That is the only way you'll be able to scale up and out the development. In order to ease development in the large pager.js got

• views (pages) that can be loaded on-demand
• view-models that can be loaded on-demand

These MVVM-triads can be developed in isolation and later on connected.

pager.js got three static methods and extends KnockoutJS with four custom bindings: page, page-href, page-hash and page-href5.

// viewModel is your KnockoutJS view model
var viewModel = {};
// pager.extendWithPage extends your
// view model with some pager-specific data
pager.extendWithPage(viewModel);
// apply your view model as normal
ko.applyBindings(viewModel);
// start the pager. Will listen to hashchange and
// show/hide pages depending on their page IDs
pager.start();

<a data-bind="page-href: 'somePagePath'"></a>

Calculates absolute href based on the location of the element.

<div data-bind="page: {}">
</div>

The page-binding. See configuration.

The configuration options for the page-binding.

ID of scoped page that a router should react to. E.g. start or user/me. If the id is ? (wildcard) it will match anything if no other page in the same parent match.

• Setup
• Deep Navigation
• Matching Wildcards
• Deep Navigation with Wildcards

That can change the scope of elements descendants. The same behavior as the normal with-binding.

• Change Binding Context

Sets the view model of elements descendants async after the page is shown. This is useful so you can extract sub pages view models to other .js-files.

• Lazy-Bind View-Model

Source to load into element using jQuery#load. The source will be loaded once the page is processed. If it is a function it is invoked.

• Load External Content
• Load View using Custom Method

Is a method/event/callback to run once the source (or sourceOnShow) is loaded.

• Load External Content

Source to load into element using jQuery#load when the element is displayed. Thus sub pages can be extracted and loaded on demand. If it is a function it is invoked.

• Lazy-Load External Content
• Load View using Custom Method

Can be set to true in order for sourceOnShow to only load the source once. If a number is specified the cache is valid for that amount of time in seconds.

• Cached Lazy-Loaded Content

Can be set to iframe in order for the source to be loaded into an iframe. If the page contains an iframe that element is used.

• Load Content into iframe
• Configure an iframe

Can be set to true in order for the page to act as a modal. If a page is a modal it can be found by child-pages to sibling-pages of the modal.

• Modals

Is called before the page is hidden.

• Custom JS when Navigating

Is called before the page is shown.

• Custom JS when Navigating

Is called after the page is hidden.

• Custom JS when Navigating

Is called after the page is shown.

• Custom JS when Navigating

Custom hide-method instead of the default $(element).hide();

• Custom Hide- and Show-Methods

Custom show-method instead of the default $(element).show();

• Custom Hide- and Show-Methods

Loader to call once the page is loaded. Can e.g. create a spinner inside the element.

• Loader

Method to call if a navigation could not find any matching page.

• Reacting to Failed Navigation

Binds URL-parameters to local observables.

• Binding URI parameters

Validates a page transition before it is happening.

• Guards

• FX

The following behaviors specify and exemplify what pager.js is capable of.

<div>
  <div data-bind="page: {id: 'bar'}">Bar</div>
  <!-- Foo is displayed -->
  <div data-bind="page: {id: 'start'}">Foo</div>
</div>

<div data-bind="page: {id:'start'}">
  <a href="#foo">Go to foo</a>
</div>
<div data-bind="page: {id: 'foo'}">
  Foo. Go to <a href="#start">start</a>
</div>

<div id="start" data-bind="page: {id: 'start'}">
    <a href="#user/fry">Go to Fry</a>
</div>

<div id="user" data-bind="page: {id: 'user'}">
    <div id="fry" data-bind="page: {id: 'fry'}">Fry</div>
</div>

<div data-bind="page: {id: 'lorem', source: 'lorem.html .content', sourceLoaded: loremIsLoaded}"></div>

The source can contain a selector (see .content above) in order to extract a fragment on the site. In the example above loremIsLoaded is a function that is triggered after lorem.html is loaded.

<div data-bind="page: {id: 'lazyLorem', sourceOnShow: 'lorem.html .content'}"></div>

sourceOnShow tells the page to load the content when the page is displayed.

<div data-bind="page: {id: 'lazyLoremCached', sourceOnShow: 'lorem.html .content', sourceCache: true}"></div>

<div data-bind="page: {id: 'lazyLoremCached5seconds', sourceOnShow: 'lorem.html .content', sourceCache: 5}"></div>

sourceCache can specify the amount of seconds the external content should be cached.

<div data-bind="page: {id: 'start'}">
  <!-- This will update href to #start/bender -->
  <a data-bind="page-href: 'bender'">Bender</a>

  <!-- This will update href to #admin/login -->
  <a data-bind="page-href: '../admin/login'">Admin Login</a>

  <div data-bind="page: {id: 'bender'}">Bender!</div>
</div>
<div data-bind="page: {id: 'admin'}">
  <div data-bind="page: {id: 'login'}">Login</div>
</div>

Based on the total path of the page the binding calculates an absolute href.

<div data-bind="page: {id: 'user', with: user}">
  <!-- Here name is user.name -->
  <div data-bind="text: name"></div>
</div>

<div data-bind="page: {id: 'user', withOnShow: someMethod('someMethod')}"></div>

someMethod must return a function that takes a callback that takes a view model.

E.g.

function requireVM(module) {
  return function(callback) {
    require([module], function(mod) {
      callback(mod.getVM());
    });
  };
}

<div data-bind="page: {id: 'admin'}"></div>
<!-- The page below match anything except 'admin' -->
<div data-bind="page: {id: '?'}"></div>

<div data-bind="page: {id: 'start'}">
      <a href="#user/leela">Go to Leela</a>
</div>

<div data-bind="page: {id: '?'}">
    Misc:
    <div data-bind="page: {id: 'leela'}">
        Leela
    </div>
</div>

<div data-bind="page: {id: 'start'}">
    <a href="#user/fry">Go to Fry</a>
</div>

<div data-bind="page: {id: 'user'}">
    User:
    <!-- {1} will be replaced with whatever matched the wildcard -->
    <div data-bind="page: {id: '?', sourceOnShow: 'user/{1}.html'}">
    </div>
</div>

<!-- An iframe will be created inside the div -->
<div data-bind="page: {id: 'user', frame: 'iframe', source: 'user.html'}"></div>

<!-- The iframe specified will be used -->
<div data-bind="page: {id: 'fry', frame: 'iframe', source: 'fry.html'}">
    <iframe sandbox=""></iframe>
</div>

It is possible to create custom widgets that jack into the pager-system. The page-binding (pager.Page-class) is possible to extend at multiple points.

Since pager is not responsible for listening on the location it is possible to circumvent the routing using the router used. Just do not use pager.start.

<div data-bind="page: {id: 'start'}">
  <div data-bind="page: {id: 'admin'}>
    <a href="#start/admin/ok">Show OK</a>
  </div>
  <div data-bind="page: {id: 'ok', modal: true, title: 'OK?'}">
        <a href="#admin">OK?</a>
  </div>
</div>

If a page is set to modal is can match IDs deeper down the hierarchy. In this case start/ok also matches start/admin/ok making the page available as a modal dialog in other contexts.

<div data-bind="page: {id: 'start'}">
  <div data-bind="page: {id: 'admin'}>
    <a href="#start/ok">Show OK</a>
  </div>
  <div data-bind="page: {id: 'ok', modal: true}">
        <a href="#admin">OK?</a>
  </div>
</div>

Losing the context is nothing special. Just navigate away form the current page.

<div data-bind="page: {id: 'fry', title: 'Fry'}">
  Fry
</div>

Setting the 'title' configuration property will update the document title when navigating to the page.

There are four alternatives:

• global registration using pager.childManager

• global data binding on body using click

• local data binding on anchor using click

• local data binding on page using beforeHide, afterHide, beforeShow, and afterShow

  // global registration using pager.childManager ko.computed(function() { var currentChild = pager.childManager.currentChildO(); if(currentChild) { // do something } });

    // local data binding on page
    <div data-bind="page: {id: 'fry', beforeHide: beforeFryIsHidden}"></div>
  
    // local data binding on anchor using click
    <a data-bind="page-href: 'fry' click: anchorClicked}">Go to Fry</a>
  

  var beforeFryIsHidden = function(page) { console.error(page); };

  var anchorClicked = function(page, e) { // otherwise the event will be stopped return true; };

  var globalClick = function() { // otherwise the event will be stopped return true; };

The click data-binding can be used to run validations before navigations. Just do not return true to prevent the navigation from happening.

<div data-bind="page: {id: 'fry', showElement: showFry, hideElement: hideFry}">
  Fry
</div>

// new default hide
pager.hideElement = function(page, callback) {
  $(page.element).slideUp(600);
  if(callback) {
    callback();
  }
};

// new default show
pager.showElement = function(page, callback) {
  $(page.element).slideDown(600);
  if(callback) {
    callback();
  }
};

var showFry = function(page, callback) {
  $(page.element).fadeIn(500, callback);
};
var hideFry = function(page, callback) {
  $(page.element).fadeOut(500, callback);
};

<div data-bind="page: {id: 'zoidberg', title: 'Zoidberg', loader: loader, sourceOnShow: 'zoidberg.html'}" />

where

textLoader: function(page, element) {
    var loader = {};
    var txt = $('<div></div>', {text: 'Loading ' + page.getValue().title});
    loader.load = function() {
        $(element).append(txt);
    };
    loader.unload = function() {
        txt.remove();
    };
    return loader;
}

// see textLoader above
pager.loader = textLoader;

<ul class="nav nav-tabs" data-bind="foreach: $page.children">
    <li data-bind="css: {active: isVisible}"><a data-bind="text: $data.getValue().title, page-href: getId()"></a></li>
</ul>

<div data-bind="page: {id: 'Slagsmålsklubben', title: 'Slagsmålsklubben',
  sourceOnShow: 'https://embed.spotify.com/?uri=spotify:album:66KBDVJnA6c0DjHeSZYaHb', frame: 'iframe'}" class="hero-unit">
    <iframe width="300" height="380" frameborder="0" allowtransparency="true"></iframe>
</div>

<div data-bind="page: {id: 'Binärpilot', title: 'Binärpilot',
  sourceOnShow: 'https://embed.spotify.com/?uri=spotify:album:67LKycg4jAoC06kZgjvbNd', frame: 'iframe'}" class="hero-unit">
    <iframe width="300" height="380" frameborder="0" allowtransparency="true"></iframe>
</div>

Both Page-objects and pager should send events whenever a navigation failed (i.e. no matching page for the route).

<a data-bind="click: function() { window.location.hash = 'failed_navigation/random/' + (Math.random()*1000).toFixed() }">
    Go to random sub-page
</a>

<div data-bind="page: {id: 'random', navigationFailed: randomFailed}">
    <ul class="nav nav-tabs" data-bind="foreach: $page.children">
        <li data-bind="css: {active: isVisible}"><a
                data-bind="text: getId(), page-href: getId()"></a></li>
    </ul>

    <div data-bind="foreach: newChildren">
        <div data-bind="page: {id: childId}">
            <span data-bind="text: childId"></span>
        </div>
    </div>
</div>

where

randomFailed:function (page, route) {
    viewModel.newChildren.push({
        childId:route[0]
    });
    page.showPage(route);
},
newChildren:ko.observableArray([])

In order to facilitate programming in the large it is useful to be able to extract views as separate components. These views should not be forced to be stored as html-fragments or be loaded with jQuery.

Thus a way to inject custom views should be possible. This is done using the source- or sourceOnShow-properties. Just supply a method instead of a string!

These properties takes a method that should take a pager.Page as first argument, a callback, and return nothing.

<div data-bind="page: {id: 'zoidberg', sourceOnShow: requireView('character/zoidberg')}" />

where

window.requireView = function(viewModule) {
  return function(page, callback) {
    require([viewModule], function(viewString) {
      $(page.element).html(viewString);
      callback();
    });
  };
};

if

// file: character/zoidberg.js
define(function() {
  return '<h1>Zoidberg</h1>';
});

A page should be able to access the information in the current route - changing a view-model.

Sending parts of the fragment identifier to variables in the view-model is possible using params.

<div data-bind="page: {id: 'search', params: {'name', 'fromdate'}}">
  <span data-bind="text: name"></span> (<span data-bind="text: fromdate"></span>)
</div>

where name and fromdate with be bound by the parameters name and fromdate.

An example route for the example above could look like

example.com/#search/tv?name=samsung&fromdate=20121010

or if HTML5 history is used

example.com/search/tv?name=samsung&fromdate=20121010

Guards are methods that are run before the page navigation takes place and that can stop the navigation from displaying a certain page.

Use the property guard: someMethod do apply the guard. The method takes three parameters: page, route and callback. If the callback is called the navigation takes place - otherwise it is stopped.

<div data-bind="page: {id: 'admin', guard: isLoggedIn}">
  This page is only accessible if the user is logged in.
</div>

where

isLoggedIn: function(toPage, route, callback, fromPage) {
    if(viewModel.loggedIn()) {
        callback();
    } else {
        window.location.href = "login";
    }
}

Use cases are login, validating steps in state machines, etc.

The reason the guard takes a callback as third argument is simply because the guard might be async - accessing a webserver for login details or asking if a valid shopping card exists etc.

pager.js is not depending on anything but jQuery, KnockoutJS and Underscore.js/Lo-Dash. You can use it together with any CSS framework. If you don't like Underscore.js you can use it together with Lo-Dash instead.

Yes. Use pager.min.history.js if you want to use it together with History.js.

• Should be possible to circumvent the routing
• Should be possible to route to custom widgets (accordions)
• Should be possible to load content into iframes
• Should send wildcards to source
• Should do deep navigation with wildcards
• Should match wildcard IDs if no other ID can match exactly
• withOnShow should lazy bind a new view model to the page
• Should change binding context using with
• Should specify relative page paths using page-href
• Should cache lazy loaded content the number of seconds specified by sourceCache
• Should cache lazy loaded content when sourceCache: true
• Should lazy load an external content into a page if sourceOnShow is declared
• Should load external content into a page using source and trigger sourceLoaded event
• Should be possible to do deep navigation
• Should navigate to page using scoped IDs.
• Should display page with id start by default

• Should be possible to add guards
• Should be possible to send URI (fragment identifier) parameters to a page
• Should be possible to load view content using a custom method
• Should be possible to navigate into modals
• Should be possible to specify loaders on pages
• Should be possible to change the page title
• Should be possible to run custom JS on "navigate failed"
• Tab panel custom widget
• Should be possible to run custom JS on "navigate to"

• Should contain common effects
• HTML5 History Boilerplate
• page-hash and page-href5 bindings for hash or html5 history
• Access to Page in withOnShow handler
• Add BeforeNavigate Event handler to allow user to stop transition

See Milestones.

Fork this repo. Install all dependencies (node.js, grunt, phnatomjs). Run all tests (grunt qunit). Run jslint (grunt lint). Make your changes. Run all tests and the linter again. Send a pull request.

pager.js is under MIT license.

Copyright (c) 2012 Oscar Finnsson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.