Jquery.mobile.lazyloader NPM

LazyLoader Widget for jQuery Mobile

Lazyloading (i.e. loading the content as it's needed during a scroll of a listview or similar control) is a great way to optimize the performance of any app that contains a list of 50 or more items. With the LazyLoader Widget for jQuery Mobile, you can easily lazyload any listview without having to write a bunch of custom code to accomplish it.

Note: This is only the client-side part of the lazyloading solution. It requires a server-side resource that returns a simple JSON formatted string. Details and examples can be found below.

Requirements
Usage
Options
Functions
- loadMore
- reset
Events
Sample

Requirements

jQuery (Tested with v2.2.4)
jQuery Mobile (Tested with v1.4.5)
Mustache (Tested with v4.2.0)
Server-side code to handle the AJAX requests

Install

$ npm install --save jquery.mobile.lazyloader

Run the following grunt command in case the dist directory doesn't exist:

$ grunt dist

Usage

Include the following files:

<link rel="stylesheet" href="node_modules/jquery-mobile/dist/jquery.mobile.min.css"/>
<script src="node_modules/jquery/dist/jquery.min.js"></script>
<script src="node_modules/jquery-mobile/dist/jquery.mobile.min.js"></script>
<script src="node_modules/mustache/mustache.min.js"></script>
<script src="node_modules/jquery.mobile.lazyloader/dist/jquery.mobile.lazyloader.min.js"></script>

Include a template in the <head>:

<script id="user" type="text/html">
	<li>
		<p class="name">Hello I'm {{ name }}</p>
	</li>
</script>

Add a list and optionally an element that indicates progress is going on:

<ul id="myListView"></ul>
<div id="myProgress" style="position: fixed; top: 50%; left: 50%; display: none">Loading...</div>

Initialize the widget with the url to get the data from and the id of the template:

$(function() {
	// Initialize the lazyloader widget
	$("#myListView").lazyloader({
		url: 'http://server.com', 
		templateId: "user", 
		$progress: "#myProgress"
	});
});

Filterable

If you are using the filterable widget in combination with this widget, the default behaviour is changed to filtering server side. The searchQuery option is set to the filter input when its content is changed. This will cause the reset function with the modified searchQuery option to be called. You are responsible for applying the filter server-side.

Server request

The request made out to the server will contain the following data:

retrieve: {number} The number of items to be retrieved.
retrieved: {number} The current number of retrieved items.
reset: {boolean} Whether or not the server data should be reset.
searchQuery: {string|null} The search query to filter with.

Server response

The server response is expected to be in a JSON format with the mandatory items key that must contain an array of objects, each representing a list item to be rendered.

{
	"items": [
		{"name": "John"}
	]
}

Options

Functions

loadMore

Loads more items.

$("#myListView").lazyloader("loadMore", timeout);

timeout: {number} The timeout before a request is sent. Defaults to the loadMoreTimeout option.

reset

Empties the list, sets the retrieved option back to 0 and sends a request for more items to the server, while also indicating a reset has been performed.

$("#myListView").lazyloader("reset", timeout);

timeout: {number} The timeout before a request is sent. Defaults to the loadMoreTimeout option.

Events

The lazyloader triggers several events during certain operations. Here are examples of how to listen for the events:

lazyloaderdoneloading

Raised when a request for more items is completed.

$("#myListView").on("lazyloaderdoneloading", function ( evt, items, data ){ });

evt: {JQuery.Event} The jQuery event.
items: {Object[]} An array of loaded items.
data: {Object} The complete JSON data returned in the response.

lazyloaderskiploading

Raised when loading of items is skipped.

$("#myListView").on("lazyloaderskiploading", function ( evt ){ });

evt: {JQuery.Event} The jQuery event.

lazyloaderalldone

Raised when all items have been loaded. No more requests will be sent after this event has been raised.

$("#myListView").on("lazyloaderalldone", function ( evt ){ });

evt: {JQuery.Event} The jQuery event.

lazyloaderreset

Raised before a reset request is made.

$("#myListView").on("lazyloaderreset", function ( evt ){ });

evt: {JQuery.Event} The jQuery event.

lazyloaderbeforerender

Raised before the loaded items are rendered. This allows you to modify the data before it's rendered in the list.

$("#myListView").on("lazyloaderbeforerender", function ( evt, items, data ){ });

evt: {JQuery.Event} The jQuery event.
items: {Object[]} An array of loaded items.
data: {Object} The complete JSON data returned in the response.

lazyloadererror

Raise when an error occurred with the ajax request or when parsing the result

$("#myListView").on("lazyloadererror", function ( evt, error ){ });

evt: {JQuery.Event} The jQuery event.

error: {Object} An object containing information about the error that occured.

	- __errorCode__: {number} The error code. 

		_Error codes_
  - __1__: An error occurred with the request.
  - __2__: An error occurred parsing the response data.
  - __3__: The specified template does not exist.