9kopb / 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.0.1.

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. Use pager.min.history.js if you want to use it together with History.js.

Release Notes

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

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

1.0.0

• A lot of cleanup and some breaking changes!

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

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

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.