jquery-paged-scroll - different approach for infinite scroll.Replace your old pagination easily.

Inspiration

Today we have a couple of good jquery "infinite scroll" plugins ,so why I wrote another one ?

Different approach - for different use case.

Most of existing plugins rely on the fact that you already have some numeric paging implemented in order to query it through provided selector for current,next and previous page and loading this page inside some element or calling callback.

For my project such approach was overhead, because I wanted only to display paged result set (json returned from public youtube and flickr api's) and replace current pagination using the "infinite scroll" interaction design pattern,where plugin will be responsible for calculation of current page according to scroll progress,so functionality can be reused.

I think the plugin will help to easily adopt infinite scroll especially in cases when working with paged result retrieved through ajax call . Because of flexibility given by the fact that plugin just calling user callback ,also http POST can be used to retrieve results.

Performance

Performance optimizations - attaching the handlers to scroll event need to be handled carefully by developer,because it can easily take the browser down. Don't believe me ? Just take a look on the John Resig article,where he explains how Twitter became unusable because of primitive handling of scroll event.

Multiple plugin instances

Support for multiple plugins on the page listening on the scroll event of the same element,but preserving their own pagination state. Look on this example: We can see 2 tabs ("Videos" and "Photos"),code responsible for tab functionality subscribes to window scroll event via the plugin and provides the callback ,but only the the callback of "visible" tab is called.

Scroll inside element

Support scrolling on different elements,not only window scroll. div,p - are supported and tested for now.

Demo:

Real world example.

KeenTour Travel startup - uses plugin to navigate through videos and photos using infinite scroll pattern.

Playground,with debug to console enabled :

Scroll on window
Scroll inside element

Getting Started

Download the production or development version.

Documentation

Options :

$('.selector').pagedScroll{
/*
   required
   custom  callback  which will be called with current page number.
*/
handleScroll:function (page, container, doneCallback) {

},

/*
required
amount of pixels or amount of percent of container 
(calculated to pixel by plugin) from bottom, to start scroll */ triggerFromBottom:'10%', /* required element where content will be inserted */ targetElement:null, /* /* html to show when loading */ loading : { html : '<div class="paged-scroll-loading"><img alt="Loading..." /></div>' }, optional,default is 0 page number to start with */ startPage:0, /* optional null means infinite scroll */ pagesToScroll:null, /* optional before page hook ,if returns false execution stops */ beforePageChanged:function (page, container) { }, /* optional after page scroll callback */ afterPageChanged:function (page, container) { }, /* optional NOT RECOMMENDED to CHANGE!!! default : true if scroll optimization used, plugin will not access DOM each time scroll is triggered and will save a lot of overhead, because of not calling callback logic each time */ useScrollOptimization:true, /* timeout in milliseconds to use in order to check if scroll change is significant enough to call the "handleScroll" callback */ checkScrollChange:500, /* frequency to check that target html is checked */ monitorChangeInterval : 300, /* if monitor target element where finally generated content is inserted */ monitorTargetChange:true, /* if use debug */ debug:false }

Examples

Call handleScroll function each time user scrolls reach the position
which is  : 10px   
from document bottom. Call the callback until currentPageNumber < yourLogic.totalNumberOfPages. Your logic inserts newly generated html to $('#element')DOM element. $(window).paged_scroll({ handleScroll:function (page,container,doneCallback) { yourLogic.getData(function(data){ var html = yourLogic.parseData(data); $('#element').append(html); }); }, triggerFromBottom:'10px', targetElement : $('#element') loader:'<div class="loader">Loading next page ...</div>', pagesToScroll: yourLogic.totalNumberOfPages });
Scroll on DOM element supported
Call handleScroll function each time user scrolls reach the position 
which equals to : 10% of the target element. Infinite scroll - because pagesToScroll is not specified. Your logic will insert newly generated html to $('#element') DOM element. $('#element').paged_scroll({ handleScroll:function (page,container,doneCallback) { yourLogic.getData(function(data){ var html = yourLogic.parseData(data); $('#element').append(html); }); }, triggerFromBottom:'10%', targetElement : $('#element') loader:'<div class="loader">Loading next page ...</div>' });

Your don't want that plugin will monitor the change of targetElement
and prefer to signal that content is loaded by calling  doneCallback().

$('#element').paged_scroll({
        handleScroll:function (page,container,doneCallback) {
            yourLogic.getData(function(data){
              var html = yourLogic.parseData(data);
              $('#element').append(html);
              doneCallback();
            });


        },
        triggerFromBottom:'10%',
        targetElement : $('#element')
        loader:'<div class="loader">Loading next page ...</div>',
        pagesToScroll: yourLogic.totalNumberOfPages,
        monitorTargetChange : false


    });

Documentation

The plugin API is quite simple and described above,but please take to your attention : Plugin provides maximum flexibility in implementing callback ,but also need to know when your callback logic is in in progress and when done in order to ignore additional onscroll events which can occur. Plugin has 2 approaches to accomplish that :

  • Monitor the targetElement html and resume until the html is changed.We suggest that you callback will load new html into the target element. Behavior is enabled by default,you can disable it by providing : monitorTargetChange : false,but then you will need to use second approach.
  • Callback function has parameter doneCallback which is passed to user code and you can just call it without any parameter to signal us you logic is done.

Coming soon

Support for horizontal scroll