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.
- 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
$ npm install --save jquery.mobile.lazyloader
Run the following grunt command in case the dist directory doesn't exist:
$ grunt dist
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"
});
});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.
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.
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"}
]
}| Option | Default | Required | Purpose |
|---|---|---|---|
| url | Empty | Yes | This specifies the URL of the server-side resource to which the AJAX post should be sent. |
| templateId | Empty | Yes | The id of the template used to create list items for the loaded items. |
| $progress | Empty | No | The selector of the jQuery element that is to be shown or hidden when a request is made. |
| eventTimeout | 100 | No | The timeout used before attempting to load more items when it is triggered by either the `scrollstart`, `scrollstop`, or `wheel` event. |
| searchTimeout | 300 | No | The timeout used before a request is sent after setting the `searchQuery` option. |
| threshold | 100 | No | This specifies the threshold in pixels for how close to the bottom of the page should the widget get before loading more items. |
| retrieve | 20 | No | This specifies how many items should be retrieved with each lazy loading ajax call |
| retrieved | 0 | No | This specifies the number of items that are currently loaded |
| searchQuery | Empty | No | The search query that is posted along in the request. Changing this option will trigger the `reset` function. |
| removeDuplicates | true | No | Removes new duplicate items loaded by a load more request. Items within a request are not compared to one another. |
| ajaxSettings | { type: "POST" } |
No | The ajax settings to use in the request. The dataType setting cannot be overwritten, it will always be `json`. The setting defined here take precedence over the deprecated `ajaxType` and `postData` options. For instance `ajaxType` will be overwritten if the ajax setting type is defined. |
Loads more items.
$("#myListView").lazyloader("loadMore", timeout);- timeout: {number} The timeout before a request is sent. Defaults to the
loadMoreTimeoutoption.
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
loadMoreTimeoutoption.
The lazyloader triggers several events during certain operations. Here are examples of how to listen for the events:
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.
Raised when loading of items is skipped.
$("#myListView").on("lazyloaderskiploading", function ( evt ){ });- evt: {JQuery.Event} The jQuery event.
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.
Raised before a reset request is made.
$("#myListView").on("lazyloaderreset", function ( evt ){ });- evt: {JQuery.Event} The jQuery event.
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.
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.
-
errorData: {*} The data offering more information about the error.
-
Navigate to the jquery.mobile.lazyloader directory and run the following command in a console to start the server and open the sample page:
npm start