Recapitulation

Pager.js contains a lot of functionality and extension-points. They can be divided into 3 parts: pager-object, page: {}-configuration, and pager.Page-class.

pager

start([id: String])

This method will start to listen to hashchange-events. Works only for newer browsers (not IE7).
This method should be called after ko.applyBindings(...).
If an ID is supplied that ID will be set as initial location.hash.

// your view model
var viewModel = {
};
// extend viewModel with a $__page__ that points to pager.page that points to a new Page
pager.extendWithPage(viewModel);
// apply your bindings
ko.applyBindings(viewModel);
// run this method - listening to hashchange
pager.start();
    

startHashChange([id: String])

This method will start to listen to hashchange-events using the jQuery hashchange plugin. You'll need to load the hashchange plugin before calling this method.
This method should be called after ko.applyBindings(...).
If an ID is supplied that ID will be set as initial location.hash.

// your view model
var viewModel = {
};
// extend viewModel with a $__page__ that points to pager.page that points to a new Page
pager.extendWithPage(viewModel);
// apply your bindings
ko.applyBindings(viewModel);
// run this method - listening to hashchange
pager.startHashChange();
    

startHistoryJs([id: String])

This method will start to listen to statechange and anchorchange-events using History.js. You'll need to load History.js before calling this method.
This method should be called after ko.applyBindings(...).
If an ID is supplied that ID will be set as initial History.pushState.

// your view model
var viewModel = {
};
// extend viewModel with a $__page__ that points to pager.page that points to a new Page
pager.extendWithPage(viewModel);
// apply your bindings
ko.applyBindings(viewModel);
// run this method - listening to hashchange
pager.startHistoryJs();
    

extendWithPage(viewModel : Object)

Create a new Page-object and set it on pager (pager.page) as well as the viewModel (viewModel.$__page__). This page-object works as the root page.
You must call this method (or do the identical thing yourself) before calling ko.applyBindings(...)

navigationFailed : Observable({page,route})

A global observable that is triggered every time a navigation fails. The observable has 2 members: route and page.

ko.computed(function() {
    var page = pager.navigationFailed().page;
    var route = pager.navigationFailed().route;
    if (page && page.getId() == null) {
        viewModel.newChildren.push({childId: route[0]});
        page.showPage(route);
    }
});
    

onBindingError : $.Callbacks

Binding Error

onSourceError : $.Callbacks

Source Error

showChild(route : String[])

Will trigger pager.page.childManager.showChild, i.e. route to the correct pages. You should call this method if you are using your own event listener for user navigation (e.g. History.js) or in some other way need to call the routing.

page : pager.Page

The root page. Got no ID. Using this reference (or $__page__ in the view model) it is possible to e.g. get a hold of all the pages on the site using pager.page.children()

useHTML5history: Boolean

Default to false. If set to true the custom binding page-href will use the custom binding page-href5, thus giving true URLs instead of hash bangs. If History.js is used (by setting pager.Href5.history = History after loading History.js) a fallback solution with hash bangs will be used for older browsers.

getParentPage(BindingContext) : Observable(Page)

Supplying the method with a bindingContext will return the first Page-instance in the context hierarchy. If no self-defined Page-instance can be found the root Page-instance will be returned.

ko.bindingHandlers['lorem-ipsum'] = {
    init:function (element, valueAccessor, allBindingsAccessor, viewModel, bindingContext) {
        // get the Page-instance that this element resides in
        var page = pager.getParentPage(bindingContext);
        // bind the text of the element to the page title
        ko.applyBindingsToNode(element, {
            text: page.val('title')
        });
    }
};
Custom Navigation Binding

Href.hash: String

Defaults to #. Can be set to #!/ if google style hash bangs are preferred.

Href5.history: Object

Defaults to window.history. Can be set to History if History.js is loaded. This object will be used by page-href and page-href5 when useHTML5history === true.

page: {}

id : String

The ID of the page. It can be either a normal name or ?. ? means that it matches against any route. The ?-ID is useful for automatically matching against a large set of structured values.

<div data-bind="page: {id: 'search'}">
    <!-- Search for product here. Will only match #search -->
</div>
<div data-bind="page: {id: 'product'}">
    <!-- List all products here. Will only match #product -->
    <div data-bind="page: {id: '?', withOnShow: loadProduct}">
        <!-- This is a page for any product since the ID is ?. Will match any #product/.* -->
        <span data-bind="text: productName"></span>
    </div>
</div>
Setup Deep Navigation Matching Wildcards Deep Navigation with Wildcards

params : String[]

A list of URL parameters (of URL-like parameters in the fragment ID) that should be bound to the view-model of the page. If you specify params: ['age'] and the parameters for the current page got an age-parameter the value of that parameter will appear inside the view-model.

<div data-bind="page: {id: 'search', params: ['name', 'price']}">
    <label>Name <input type="text" data-bind="value: name"></span></label>
    <label>Price <input type="text" data-bind="value: price"></span></label>
</div>

and the user surfs to /search?name=TV&price=200 the user will see

Binding URI parameters Parameters as objects

nameParam: String/Observable

Binding Wildcard to observable

vars: Object

Custom observables in the view

with : Object

Works as the normal with-binding.

<div data-bind="page: {id: 'fry', with: fry}">
    The age of Fry is <span data-bind="text: age"></span>
</div>

where

var viewModel = {
    fry: ko.observable({age: ko.observable(27)})
}
This member should also be possible to supply a method as withOnShow, i.e. should be possible to be either an object or a method.
Change Binding Context

withOnShow : Function(Function(Object), Page)

This member makes it possible to lazy-bind a view-model once the page is first displayed. withOnShow takes a method that should take 2 arguments: a callback (that should be feeded the view-model) and the current Page-object.

This property is very useful when you want to split up your view-model for your single page application into multiple smaller view-models that can still communicate with each other. You might feed a page a view-model for a certain item.

If you set sourceCache: true the view-model will not reload every time you revisit the page.

<div data-bind="page: {id: '?', withOnShow: Cool.loadUser}">
    <h1 data-bind="text: userName"></h1>
</div>
Cool.loadUser = function(callback, page) {
    $.get('service/users/' + page.currentId, function(data) {
        callback(ko.mapping.fromJSON(data));
    });
};
This member should also be possible to supply an object as with, i.e. should be possible to be either an object or a method.
Lazy-Bind View-Model

source : String / Function(Page, Function())

Load content into the page from an external source.

Load External Content Load View using Custom Method

sourceOnShow : Function(Page, Function())

While source loads the content into the page directly the configuration sourceOnShow loads the content into the page when the page is first requested. This configuration can be further controlled using sourceCache.

Lazy-Load External Content Load View using Custom Method

sourceLoaded : Function(Page)

Register a callback whenever an external source (source or sourceOnShow) is loaded into the page. Useful for e.g. post-processing.

Load External Content

sourceCache : Boolean / Number

sourceCache will control both the caching of the lazy-loaded source and the lazy-loaded view-model.

If not set (or false) the lazy-loaded model (withOnShow) and view (withOnShow) will be requested every time the page is displayed.

If set to true both the lazy-loaded model and view are cached.

If set to a number the lazy-loaded view is cached that amount of time in seconds.

Cached Lazy-Loaded Content

frame : String

By specifying frame: 'iframe' the external source is loaded into an iframe instead.

Load Content into iframe Configure an iframe

modal : Boolean

If a page is configured as modal: true it can appear in child-pages of sibling-pages to the modal page.

Modals

beforeHide : Function(Page)

Custom JS when Navigating

beforeShow : Function(Page)

Custom JS when Navigating

afterHide : Function(Page)

Custom JS when Navigating

afterShow : Function(Page)

Custom JS when Navigating

hideElement : Function(Page,Function())

Custom Hide- and Show-Methods

showElement : Function(Page)

Custom Hide- and Show-Methods

fx : String

FX

loader : Function(Page,Node)

Loader

navigationFailed : Observable({page:Page,route:String[])

Reacting to Failed Navigation

onBindingError : Function({page:Page,url:String,xhrPromise:$.Promise})

Binding Error

onSourceError : Function({page:Page,url:String,xhrPromise:$.Promise})

Source Error

guard : Function(Page,String[],Function(),Page)

The first argument is the page being navigated to, the second argument is the route, the third argument is a callback and the fourth argument is the page being navigated from.

Guards

urlToggle :String

Control when the page will be displayed or hidden. There are three possible values: null (default), show or none. null is the normal behaviour. show makes the page show when the route is matching, but wont automatically hide. none means that the page does not react to the route. You'll need to control the visibility of the page in some other way. Pages with urlToggle: 'none' will be visible by default.

Pages that only toggle on

title : String

Controls the page title if set.

Show start page by default

pager.Page

element : Node

Custom Widgets Custom Show- and Hide-Methods Loaders

viewModel : Observable/Object

The view-model of the page.

children : ObservableArray(Page[])

Tab Panel

child(String) : Observable(Page)

Pages that only toggle on

parentPage : Page

The parent page, or null if the page is the root page (pages.page).

currentParentPage : Observable(Page)

The current parent page. Normally it is the same as parentPage but for modal pages it change change.

currentChildPage : Observable(Page)

The currently visible child-page of the page. Observe that the current child page does not need to be in the collection children since the current child page can be a modal page!

currentId : Observable(String)

Get the current ID of the page. You should normally call this method instead of getId since the current ID can change for wildcard-pages (?).

isVisible : Observable(Boolean)

Tab Panel

val(String) : Object

Get an un-boxed configuration property from valueAccessor by the key specified. If you want to get hold of e.g. the configuration property beforeHide you should call somePage.val('beforeHide') instead of somePage.valueAccessor.beforeHide since both valueAccessor and beforeHide can be observables!
All the possible keys for the configuration object can be accessed using val (e.g. title, params, with, withOnShow).

getId() : String

The ID of the page. You should normally call currentId instead since the ID can change for wildcard pages.

init() : {controlsDescendantBindings:true}

Custom Widgets

getFullRoute() : [String]

Returns the full route of the page.

Custom Navigation Binding

nullObject : pager.Page

Is a null-object of pager.Page. It is useful in computed observables as a temporary Page-instance before the correct Page-instance is loaded or parsed.