Using jQuery Mobile ListView

What Will I Learn?

In this tutorial, we're going to look at what JQuery Mobile uses to represent lists, and how capable they really are.

Requirements

jQuery Mobile Framework

Difficulty

Intermediate

Tutorial Contents

• Defining List Views
• List View UI
• Nested ListViews
• User Input
• Capturing User Input
• List Dividers and Bubble Counts
• Split Button List

Using jQuery Mobile ListView

In this tutorial, we're going to look at what JQuery Mobile uses to represent lists, and how capable they really are.

Everybody needs lists of data within their web applications. A list is one of the most common user interface controls used. Lists vary in form; they may be simply a list of entries (like country names), tabular in form (a grid), or even appear collapsed and respond to user input (combo box). Regardless of the differences between these controls, they essentially represent a list.

In this tutorial, we're going to look at what JQuery Mobile uses to represent lists, and how capable they really are.

Defining List Views

JQuery Mobile supports a list by using the listview widget. A list is defined by an ordered or unordered list applying the data-role attribute, with a value of "listview". Each list item (LI tag) is an entry in the list, and can contain a variety of markup contents. For instance, a list may have an H3 element to represent the list item's header. In addition, if a list needs to display additional content, it can do so using a paragraph tag (P). Alternatively, a list can solely be a hyperlink directing the user to another view or page.

Listing 1 contains a simple list. Each list has a header, and a paragraph representing the description. The entire list item's content is wrapped in a hyperlink; this permits the user to click anywhere on the row to perform a redirection.

Listing 1: List View UI

<ul data-role="listview">
    <li>
        <a href="#options">
            <h3>
                Application Settings
            </h3>
            <p>
                Settings for the application to use.
            </p>
        </a>
    </li>
    <li>
        <a href="#options">
            <h3>Power Settings</h3>
            <p>
                Settings for managing the power of the device.
            </p>
        </a>
    </li>
    <li>
        <a href="#options">
            <h3>Wifi Settings</h3>
            <p>
                Settings for the WIFI connections available.
            </p>
        </a>
    </li>
</ul>

Notice the use of an unordered list; however, an ordered list (OL) can be used in the same fashion. Each item in the list is given a value (sequential number by default).

As with many other types of widgets, the list view widget supports nesting of lists. A list defines another ordered or unordered list with the listview data role as a child of a list item, as depicted in Listing 2. Nested lists function differently than other widgets do; nested lists provide a drill-through feature, similar to the navigation capability provided by hyperlinks in a multi-page template.

This means that upon selecting an item in the list, the user sees a transition to another list displaying the inner list's contents. The header of this page is the defined title of the list (specified in the H3 element). Many levels of nesting are supported; while Listing 2 displays 2 levels of nesting, much more is supported.

Listing 2: Nested ListViews

<ul data-role="listview">
    .
    .
    <li>
        <h3>Delete User</h3>
        <div>
            Delete an existing user from the system.
        </div>
        <ul data-role="listview">
            <li>
                <h3>Andy</h3>
                <ul data-role="listview">
                    <li>
                        <a href="#DeleteUserConf">Yes, Delete</a>
                        Delete this user permanently.
                    </li>
                    <li>
                        <h3>No, Cancel</h3>
                        Cancel this operation.                              
                    </li>
                </ul>
            </li>
        </ul>
    </li>
</ul>

Hierarchical lists provide the advantage of not displaying too much data or too many options to the user at one time. Additionally, not much additional setup is needed to support this.

User Input

A list provides a template to the user; as such, lists can accept user input by defining an input control within the list. For instance, take a look at Listing 3, which defines a textbox within the list item.

Listing 3: CapturingUser Input

<ul data-role="listview">
    <li>
        <h3>Create New User</h3>
        <p>
            Create a new user in the system:
            <input type="text"/>
            <select>
                <option>User</option>
                <option>Power User</option>
                <option>Administrator</option>
            </select>
            <a href="#CreateUserConf" data-role="button" data-inline="true">Save</a>
        </p>
    </li>
</ul>

List views can define whatever content it needs to within the header or description. Here, we have a form that creates a new user with the given name and role defined. As you can see, it's very easy to embed additional content into a view; it's even easier to define since JQuery Mobile styles each input for us and applies a block layout for the textbox and drop down. To use only the amount of space required, add the data-inline attribute with a value of true.

Other Features

Lists support a variety of other features. Sometimes, with larger lists, providing a divider between groups of items, such as the first character of the entry, can be a helpful feature. This can be a common feature applied to list of names, for instance. This can be achieved by applying a list divider between the groups of items. For instance, Listing 4 contains a divider between the names grouped by the first letter of the person in the contacts list. Also notice the use of a span below too.

Listing 4: List Dividers and Bubble Counts

<ul data-role="listview">
    <li data-role="list-divider">A</li>
    <li>
        <h3>Amy</h3>
        <span class="ui-li-count">1</span>
    </li>
    <li>
        <h3>Andy</h3>
        <span class="ui-li-count">2</span>
    </li>
    <li>
        <h3>Aaron</h3>
        <span class="ui-li-count">3</span>
    </li>
    <li data-role="list-divider">B</li>
    <li>
        <h3>Bob</h3>
        <span class="ui-li-count">9</span>
    </li>
    <li>
        <h3>Brad</h3>
        <span class="ui-li-count">5</span>
    </li>
    <li>
        <h3>Brian</h3>
        <span class="ui-li-count">3</span>
    </li>
</ul>

Listing 4 displays another feature with lists, which is the ability to display a value surrounded by a bubble icon. Applying the ul-li-count CSS class applies the bubble around the value defined within the span, giving it a special look. Listing 4 uses the bubble to indicate the speed dial number of the contact. Another example is an email inbox view, where the value in the bubble contains the number of total or unread messages in the given box (inbox, sent, deleted, etc.). Notice how the element within the bubble exists within the list's content, and yet JQuery Mobile applies specific position for this item.

The last type of list we'll talk about here is the split button list format, where the panel is split into two – the main content of the list, and an icon to the right of the list displaying an icon that triggers some functionality. The split button format uses the second link to display as the icon on the right side. The icon displays the value defined by the data-split-icon attribute of the list. Take a look at the list in listing 5.

Listing 5: Split Button List

<ul data-role="listview" data-split-button="true" data-split-icon="gear">
    <li>
        <a href="#options">
            Application Settings
        </a>
        <a href="#dialogpage" rel="dialog">Opt</a>
    </li>
    <li>
        <a href="#options">
            Power Settings
        </a>
        <a href="#dialogpage" rel="dialog">Opt</a>
    </li>
    <li>
        <a href="#options">
            Wifi Settings
        </a>
        <a href="#dialogpage" rel="dialog">Opt</a>
    </li>
</ul>

Here the Opt text of the link never displays, but a gear displays in its place. When the gear icon is clicked on, it displays the dialog page. Clicking on the list item navigates to the options page.

Conclusion

The list is one of the most common types of controls used, and is represented in JQuery Mobile by the list view widget. This widget is an ordered or unordered list, which each item representing the list's content and/or additional navigable lists. There are a variety of options that can be provided for the list, such as using an icon on the right for the list (split button approach), displaying a bubble value on the list, adding dividers, and more.

---

Posted on Utopian.io - Rewarding Open Source Contributors

---