finnsson / pagerjs

The Single Page Application Framework for KnockoutJS

pager.js

one having or covering a specified number or kind of pages
  - Merriam-Webster

See the demo.

pager.js is a JavaScript library based on KnockoutJS and jQuery 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.

This readme is for version 1.1.0

Getting Started

See the demo.

Install

Download

Using npm

npm install pagerjs

Dependencies

• KnockoutJS
• jQuery

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

Philosophy

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.

FAQ

Can I use it together with...

pager.js is not depending on anything but jQuery and KnockoutJS. You can use it together with any CSS framework.

Can I use true URLs instead?

Yes. PagerJS supports true URLs with History.js.

Release Notes

1.1.0

• Allow for ctrl/command/shift new windows for html5 links.
• Allow arrays in GET parameters
• Allow multiple methods in route guards
• Various bug fixes

1.0.1

• Work with Knockout 2.3
• hash urls
• withOnShow is not updating route after source is loaded
• Show/Hide Events event don't occur
• toJSON refinements
• pagerjs AMD support replies on global $ variable
• withOnShow not updating on navigation
• Added bower.json for dependency installation when pulling in this module.
• Do not overwrite nameParam on view model if it is already defined

1.0.0

• A lot of cleanup and some breaking changes!

0.7

• Remove underscorejs dependency
• pager.start id does not honor pager.Href.hash
• Sending wildcards to the viewmodel
• Should handle pages that does not react to URL changes
• Should handle pages that does not hide on URL changes
• Should handle exceptions in with/withOnShow
• Should handle exceptions on source/sourceOnShow

0.6

• 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
• page-href should be possible to feed with a page-instance
• Should be possible to use hash bang #!/ instead of hash
• Scoped pure view observables using vars
• Wildcards should deep-load content if configured so
• Should be able to change initial page
• Demo as is does not work in IE7

0.4

• 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"

0.2

• 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

Roadmap

See Milestones.

How to Contribute

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.

Contributors

finnsson

GilesBradshaw

tedsteen

Shildrak

adimkov

imrefazekas

altmann

huochunpeng

Munter

alvingonzales

CuinnWylie

DKhalil

License

pager.js is under MIT license.

Copyright (c) 2013 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.

pagerjs's Issues

Should be possible to specify loaders on pages

Should be possible to send URI (fragment identifier) parameters to a page

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

Should send wildcards to source

<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>

Should specify relative page paths using `page-href`

<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.

page-hash and page-href5 bindings for hash or html5 history

Two new bindings should be created.

page-hash for normal hash handling and page-href5 for html5 history.

The current page-href should be either one - depending on configuration (pager.useHTML5history)

Should be possible to run custom JS on "navigate failed"

delete me?

my mistake completely. works as intended.

Don
have a great day

Should be possible to use hash bang (#!/) instead of hash

demo: Lazy Load External Content not working same as Load External Content

In playing with demo page Lazy Load External Content (on a local server since online demo is currently out of sync with repo content (e.g., missing CSS class linenums)), despite having CSS classes prettyprint linenums, line numbers are not shown. If I manually run prettyPrint() in the console it works right. If I add page property callback source: prettyPrint(), it also doesn't work. Using an instrumented callback in source, it looks like refresh of the page triggers calling the callback twice which seems like another bug? Is this a known limitation / working-as-designed / user error?

Should cache lazy loaded content when `sourceCache: true`

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

Should be possible to run custom JS on "navigate to"

IE8 Date.now

IE8 throws an error due to Date.now not existing.

Should have

if (!Date.now) {
Date.now = function() {
return new Date().valueOf();
};
}

At the head of pager.js

Access to Page in withOnShow handler

First, thanks for creating a really nice library!

It would be nice to have access to the Page object when dynamically fetching viewmodels in "withOnShow". I modified the source for withOnShow to pass "this", just like you are currently doing for sourceOnShow:
I replaced
572 - }, this));
572 + }, this), this);

This allow me to retrieve specific data for my views based on the route, eg

http://domain.name.com/order/56

 <div data-bind="page: {id: '?', withOnShow: MyNamespace.Order.GetModel()}"></div>

MyNamespace.Order = {
    GetModel: function () {
        return function (callback, page) {
            $.getJSON('/api/orders/' + page.currentId, function (data) {
                var viewModel = new MyNamespace.Order.ViewModel(data);
                callback(viewModel);
            });
        };
    }
};

Off course, ability to use wildcards would be even better, to say something like:

 <div data-bind="page: {id: '?', withOnShow: MyNamespace.Order.GetModel({1})}"></div>

But I don't think this is an easy addition? However, I hope you will consider adding the page parameter as described above.

Uncaught TypeError: Object #<Object> has no method 'start'

Current (0a1f5b0bc15f4731345e88920a64093c63b4a335) pager.js causes
Uncaught TypeError: Object #<Object> has no method 'start' for standard initialization code, while dist/pager.min.js works (this was somewhat difficult to track down). I prefer to use pager without requirejs.

Scoped pure view observables using `vars`

<!-- x and y are now available as observables, but only in the view (not the view-model) -->         
<div data-bind="page: {id: 'foo', vars: ['x','y']}">                                                 
  <span data-bind="text: x"></span>                                                                  
  <span data-bind="text: x"></span>                                                                  
</div>                                                                                               

This is useful for effects that has nothing to do with the view-model.

Should be possible to add guards

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(page, route, callback) {
    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.

Named binding of child elements using `bind-child`

<div data-bind="page: {id: 'foo'}">                                              
  <div>                                                                          
    <span data-bind="page-child: 'name'"/>                                       
    <span data-bind="page-child: 'age'"/>                                        
  </div>                                                                         
</div>                                                                           

Now name and age are available in the Page-instance under the elementChildren-observable, e.g. this.elementChildren().name() and this.elementChildren().age().

Load external content with Wildcard and nested navigation

Firstly, thanks for your job, it's good idea and implementation.

I'm trying to implement following scenario:

in the main page only one "navigation node"

<div data-bind='page: {id: '?', sourceOnShow: '{1}.html'}'><div>

each loaded element have own navigation... for example into modal view.

Problems:

1. after recent update external sources not loading into main page, but loaded after page refresh. Url is changed, but nothing happens
2. nested navigation doesn't work. Url is changing, but nothing happens.

Maybe it's wrong way, but looks like it's should work.

thanks.

Should be possible to route to custom widgets (accordions)

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.

One custom widget (page-accordion-item) is already implemented.

<div data-bind="page: {id: 'employee'}">
    <div data-bind="page-accordion-item: {id: 'zoidberg'}">
        <a href="#employee/zoidberg">Dog</a>
        <div>Zoidberg Information</div>
    </div>
    <div data-bind="page-accordion-item: {id: 'hermes'}">
        <a href="#employee/hermes">Cat</a>
        <div>Hermes Information</div>
    </div>
</div>

Should react to removed and added child pages

When a child page is removed and later a page with the same page is added the newly added child page should be visible.

demo: direct link requires reload?

I noticed when I open a tab and paste a URL (e.g., http://oscar.finnsson.nu/pagerjs/demo/#guards) it doesn't fully render -- only the header and footer show -- until I reload the page (tried on Firefox 15 and Chrome 22 on OS X). Is this expected behavior?

Mapping plugin does not work

The knockoutjs mapping plugin and ko.toJS function doesn't work. I was able to figure out that it is trying to convert the property added to the object by pagerjs and eventually causing javascript to run out of memory and throw an error.

Should be possible to do deep navigation

<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>

HTML5 History Boilerplate

An example application of using pager.js together with History.js can be found in boilerplate.

Should be possible to change the page title

Add BeforeNavigate Event handler to allow user to stop transition

An example would be validation.

If validation fails, you do not want the transition to be performed.

It would be nice if the items that are passed to the event include the current page and the page the user is attempting to navigate to.

If this is the navigate to backlog item then please ignore.

Should match wildcard IDs if no other ID can match exactly

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

Wildcards should deep-load content if configured so

<a href="some/other/url">Go to some/other/url.html</a>                   

<div data-bind="page: {id: '?', deep: true, sourceOnShow: '{?}.html'}>   
</div>                                                                   

Should be able to change initial page

Something like pager.start("id") would be nice!

page-href should be possible to feed with a page-instance

If a page-href-binding is feed with a page-instance the URL to the page is automatically calculated.

Should do deep navigation with wildcards

<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>

Should change binding context using `with`

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

Should display page with id start by default

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

`withOnShow` should lazy bind a new view model to the page

<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());
    });
  };
}

Tab panel custom widget

<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>

pager.start(id) does not honor pager.Href.hash

When doing pager.start(id) the pager.Href.hash is not applied to the new window.location. I don't know about the rest of the start methods.

Should be possible to navigate into modals

Should handle exceptions in with/withOnShow

Should contain common effects

The effects zoom, flip, fade and slide.

Should navigate to page using scoped IDs.

<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>

Should load external content into a page using `source` and trigger `sourceLoaded` event

<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.

Demo as is does not work in IE7

Is it just me or does the demo not work in IE7? I can go to different hashes, but the content on the page is not reflected.

Should lazy load an external content into a page if `sourceOnShow` is declared

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

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

demo: local server issue with #recapitulation

In running the demo from a local server using the following procedure:

1. cd into demo dir of repo (fork) clone
2. run python -m SimpleHTTPServer
3. use browser (tried Chrome and Firefox) to visit "pages", e.g., http://localhost:8000/#guards

All pages seem to work fine except http://localhost:8000/#recapitulation which renders sections weird

Compared to correct rendering on your server http://oscar.finnsson.nu/pagerjs/demo/#recapitulation

Should handle exceptions on source/sourceOnShow

Should cache lazy loaded content the number of seconds specified by `sourceCache`

<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.

Should be possible to circumvent the routing

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.

Remove underscorejs dependency

pager.js should at the moment not depend on underscore.js since most things can be solved with jQuery.

Should be possible to load view content using a custom method

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>';
});

Should be possible to load content into iframes

<!-- 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>