Tutorial: JQMListView Object

April 18, 2012

The JQMListView object is a easy way to create native-style lists of items containing text, images, badges and more. In this tutorial, we’ll explore this object and experiment with the different ways it can be used to enhance your apps. You can follow along step-by-step, or view the completed app (with source code) by selecting it from the Sample Gallery within Handheld Designer.

Page 1: Drag & Drop

Start a new project, which begins with a single page called page1. Since we’ll be creating several similar pages, we’ll add a header to each one to help us tell them apart: Drag a JQMHeaderToolbar object from the Object Palette and drop it onto the page, and change its title property to “Page 1” using the property editor.

In this example, we’ll cover the basics of creating a list view at design-time. Drag a JQMListView object from the Object Palette and drop it onto the page. By default, the list view is populated with three default items. Let’s remove them, and add ones of our own.

With the list view selected, click the “Edit” button on the items property in the property editor, opening the list view editor. (As a shortcut, double-clicking a JQMListView object in the design view also opens the list view editor.) The list view editor allows you to add, re-order or remove list view items and dividers, and define their labels, themes, badges, thumbnail images, and on-click event handlers.

Using the editor, delete the existing items by selecting them and pressing “delete” (or click the “-” button at the bottom of the list view editor). Then, add your own items.

Adding Items

Add items by clicking the ”+” button at the bottom of the list view editor, or clicking the first empty row. Set the text that will appear in the new row by entering it in the row’s “label” column. (In this example, I’ve entered a number of rock musicians.)

Dividers

Group your list by defining dividers. Dividers are styled differently than regular items and serve to visually organize the list. You can define a divider by checking the “Divider” checkbox. (Note that dividers only support the “label” and “theme” property. When an item is defined as a divider, the other columns in that are cannot be edited.)

Re-ordering Items

After you’ve defined your items, you can change their order by simply dragging and dropping them within the list view editor. Change the order of your list so the items are sorted alphabetically, or by another criteria you choose. (By awesomeness, for example. Note that placing Stewart Copeland in a position other than first, while wrong, will not generate a syntax error.)

Changing Themes

Like other jQuery Mobile controls, individual list view items and dividers can be assigned a “theme” to control its color scheme. By default, items use the “c” theme and dividers use the “b” (i.e. blue) theme, but you can change those values by selecting a different theme from the pop-up menu in the “theme” column.

Badges

Each (non-divider) item can have an optional “badge” associated with it, shown in a bubble on the right side of the item. These are often used to display a “count” associated with that item. Enter a number (or other text) into the “badge” column to have an item display a badge bubble.

Thumbnail Images

Each (non-divider) item can have an optional thumbnail image associated with it. This image is displayed on the left side of the item, and will be scaled to 80 pixels by 80 pixels. Set a thumbnail by entering an image in the “thumbnailImage” column. This could be an image stored as a project resource, or the full URL to an external image.

Event Handlers

To define a handler to be called when the user taps an item, select it from the “onClick” popup menu (or select “Create New Event Handler…” to create a new event handler function). You can define a different event handler function for each item, or assign the same handler to every item in your list view.

Note that an event handler defined on an individual item will override any onClick handler assigned to the list view itself. Since the this variable in the context of the event handler refers to the item tapped, it’s more common to assign an onClick handler on the list view, rather than separate handlers for each item.

On items with a defined event handler, click the arrow on the right edge of a row as a shortcut to edit the item’s event handler code.

Page 2: Adding (and Removing) List View Items in Code

In addition to adding items in the list view editor, you can also add items and dividers dynamically in code. We’ll create a new page called “page2” to explore this capability by clicking the “New Page” toolbar button (or selecting “New Page” from the “File” menu). If the id property is not “page2”, go ahead and make that change now. As with the first page, add a JQMHeaderToolbar to the page and set it’s title property to “Page 2”.

Before we start building the code on “Page 2”, a little housekeeping: Since our app will start on “page1”, we need a simple way to get to our new page. Go back to page1 by selecting it from the Project pane, and select the JQMHeaderToolbar. Make the following changes in the property editor:

• Set the rightButtonLabel property to “Next”
• Set the rightButtonIcon property to “arrow-r”
• Set the rightButtonIconpos property to “right”
• Set the rightButtonTheme property to “b”

Finally, open the Events group and create a new event handler for the rightButtonOnClick event, with the following code:

function header1_rightButtonOnClick(event) {

	application.gotoPage("page2");

}

This will add a button to the header that, when tapped, will display “page2”.

Returning to “page2” (by selecting it from the Project pane), drag a JQMListView object from the Object Palette and drop it onto the page. We’ll be dynamically adding items to this list view, so note its id. (The remainder of this section assumes the id is “listview1”.) Open the list view editor by clicking the “Edit” button on the items property, or double-clicking the JQMListView object in the design view. Delete the default items from the list view so we’re starting with an empty list.

We’ll place the code that adds the items to the page’s onLoad event. This event executes when the page loaded, so is a convenient location for code that you want executed to initialize objects on your page.

To create the event handler, select the HDPage object by clicking outside the page in the Design view, or select it from the object menu above the property editor. Open the “Events” property group and click the “Create” button for the onLoad event. This should create a new event handler and open its code in the function editor.

Adding Items

We’ll add items to the list view using the appendItem() method. This method adds a new item to the list view, and returns a JQMListViewItem object representing the new item that you can use to set the items properties.

For example, to add a few items to the empty list view:

function page2_onLoad(event) {

	var item; 
	
	item = listview1.appendItem();
	item.label = "Jimi Hendrix";
	
	item = listview1.appendItem();
	item.label = "Eric Clapton";
	
	item = listview1.appendItem();
	item.label = "Stevie Ray Vaughn";
}

This will add three items to the list view. (To check, run the project by clicking the “Run” button, then when your app loads, select the “Next” button your created in the toolbar on page1. When page2 loads, you should see your list view with the items added in the onLoad handler.)

There’s also a shortcut to using the appendItem() method: you can initialize the new item’s label by passing it to the the appendItem() method:

function page2_onLoad(event) {

	listview1.appendItem("Jimi Hendrix");
	listview1.appendItem("Eric Clapton");
	listview1.appendItem("Stevie Ray Vaughn");
}

Adding Dividers

Similar to items, dividers are added to the list view using the appendDivider() method. Here’s the code from above, with the addition of a divider:

function page2_onLoad(event) {
	
	listview1.appendDivider("Guitar");
	listview1.appendItem("Jimi Hendrix");
	listview1.appendItem("Eric Clapton");
	listview1.appendItem("Stevie Ray Vaughn");
}

Note that while the appendDivider() method returns a JQMListViewDivider object, it also supports the shortcut of setting the new divider’s label by passing it as an argument to appendDivider().

Inserting Items

Use the insertItem() method when you’d like to add a new item somewhere other than the end of a list. The first argument is a number representing the item before which the new item will be inserted. (Like arrays, item numbering starts at zero. So calling listview.insertItem(0) would insert an item before the first item in the list.)

Removing Items

The JQMListView and JQMListViewDivider objects support a remove() method that will remove that item from the list view. For example:

function page2_onLoad(event) {
	
	listview1.appendDivider("Guitar");
	listview1.appendItem("Jimi Hendrix");
	listview1.appendItem("Eric Clapton");
	
	var item = listview1.appendItem("Stevie Ray Vaughn");
	
	// now remove the item we just added:
	item.remove();
}

In addition, the JQMListView supports a removeAllItems() method that will empty the list view of all items and dividers:

function page2_onLoad(event) {
	
	listview1.appendDivider("Guitar");
	listview1.appendItem("Jimi Hendrix");
	listview1.appendItem("Eric Clapton");	
	listview1.appendItem("Stevie Ray Vaughn");
	
	// now remove the all the items just added:
	listview1.removeAllItems();
}

Page 3: Manipulating List View Items in Code

Regardless of whether items are added to a list view at design-time, or in code, you can manipulate those items from your code.

To begin, create a new page (“page3”) and, as with the previous page, perform the following setup:

• Create a new page (“page3”)
• Add a “Next” button to page2’s toolbar that sends the user to the new “page3”.
• Add a header toolbar to page3 with the title “Page 3”
• Delete the default list view items and add some of your own (as you did on “Page 1”)
• Add an onLoad handler to the page to hold our code.

Enumerating Items/Dividers

The JQMListView object has an items property, which is an array of all items (or dividers) in the list view. You can use this property to enumerate all of the items in a list view.

For example, to print each of the item titles to the debugging console, you could:

function page3_onLoad(event) {
	
	for(var i = 0; i < listview1.items.length; i++)
	{
		console.log("label for " + i ": " + listview1.items[i].label);
	}
}

To make it easier to differential dividers from items when enumerating the items array, dividers have a read-only divider property that evaluates to true. For example, to exclude dividers from the code above:

function page3_onLoad(event) {
	
	for(var i = 0; i < listview1.items.length; i++)
	{
		if(listview1.items[i].divider)
		{
			continue;
		}
		
		console.log("label for " + i ": " + listview1.items[i].label);
	}
}

Setting Item Properties

The JQMListViewItem object represents a single item in a list view. The are returned by the appendItem() and insertItem() methods, or can be accessed in the list view’s items array property. Once you have a JQMListViewItem object, you can change its properties to:

• Alter its text with the label property
• Change it’s color scheme with the theme property
• Give it a badge bubble with the badge property
• Define a thumbnail image with the thumbnailImage property
• Define an event handler to be called when the item is tapped with the onClick property.

For example, the following code adds a badge bubble (set to a random number) to the items in the list view:

function page3_onLoad(event) {
	
	for(var i = 0; i < listview1.items.length; i++)
	{
		if(listview1.items[i].divider)
		{
			continue;
		}
		
		listview1.items[i].badge = Math.round(Math.random() * 10);
	}
}

Event Handlers

The JQMListView object can be assigned an onClick event handler to be called when any of its items are tapped. As with other objects, this assignment can be performed in the property editor at design-time, or at run-time.

In the context of most event handlers, the this variable refers to the object that triggered the event. In this case, this refers not to the JQMListView object, but the actual JQMListViewItem that was tapped by the user.

function page3_onLoad(event) {

	listview1.onClick = function(event) {
		// "this" is the item, not the list view
		this.label = "Item tapped";
	};	
}

In addition to the onClick event handler on the list view, each JQMListViewItem object can be assigned its own onClick event handler that supersedes any defined on the list view. The assignment of individual item event handlers can be performed in the list view editor at design-time, or at run-time. An example of run-time assignment:

function page3_onLoad(event) {

	listview1.items[3].onClick = function(event) {		
		// "this" is the item tapped
		this.label = "Fourth item tapped";
	};
}

Summary

I hope you’ll find that the JQMListView object makes it easier to create beautiful mobile web apps. As always, I welcome your feedback; use the Contact link at the top of the page to send your questions, comments and suggestions.

---

---

Posts by Category

• Reviews (1)
• Games (1)
• Releases (9)
• Tutorials (9)

Copyright © 2010-2013, Handheld Designer, LLC, All Rights Reserved.
Made by hand in New England, USA.