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.
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
onSourceError : $.Callbacks
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') }); } };
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
.
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>
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
nameParam: String/Observable
vars: Object
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)}) }
withOnShow
, i.e. should be possible
to be either an object or a method.
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)); }); };
with
, i.e. should be possible
to be either an object or a method.
source : String / Function(Page, Function())
Load content into the page from an external source.
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
.
sourceLoaded : Function(Page)
Register a callback whenever an external source (source
or sourceOnShow
)
is loaded into the page. Useful for e.g. post-processing.
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.
frame : String
By specifying frame: 'iframe'
the external source is loaded into an iframe instead.
modal : Boolean
If a page is configured as modal: true
it can appear in child-pages of sibling-pages
to the modal page.
beforeHide : Function(Page)
beforeShow : Function(Page)
afterHide : Function(Page)
afterShow : Function(Page)
hideElement : Function(Page,Function())
showElement : Function(Page)
fx : String
loader : Function(Page,Node)
navigationFailed : Observable({page:Page,route:String[])
onBindingError : Function({page:Page,url:String,xhrPromise:$.Promise})
onSourceError : Function({page:Page,url:String,xhrPromise:$.Promise})
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.
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.
title : String
Controls the page title if set.
element : Node
viewModel : Observable/Object
The view-model of the page.
children : ObservableArray(Page[])
child(String) : Observable(Page)
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)
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}
getFullRoute() : [String]
Returns the full route of the page.
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.