O'Reilly logo

jQuery Mobile: Up and Running by Maximiliano Firtman

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

Chapter 4. Lists

Up to now, we have created very simple pages rendered by jQuery Mobile. The next big step is to use rich controls and views provided by the framework; in this case, lists. Almost every mobile project will have at least one list in its content, so that is why we are going to address this first.

It’s difficult to start this chapter with a definition. You already know what a list is. And there is nothing new I can say about them as a general term. Inside jQuery Mobile world, a list is just an ordered (ol HTML element) or unordered (ul HTML element) list inside a page with at least one list item (li HTML element) and the role defined as listview using the HTML5 syntax data-role="listview".

If you want to just show a bulleted or numbered list, you can always render typical ul and ol HTML elements; just remember to not assign any JQM role.

Lists are a powerful solution for many uses inside the framework, as we are going to see in next pages.

The most typical list is an unordered one (ul) that simply exists inside a page without other content. Let’s see a simple sample, illustrated in Figure 4-1:

<!DOCTYPE html>
<html>

<head>
 <meta charset="utf-8" />
 <title>Up and Running with jQuery Mobile</title>
 <link rel="stylesheet" href="jquery.mobile-1.0.min.css" />
 <script src="jquery-1.6.4.min.js"></script>
 <script type="text/javascript" src="jquery.mobile-1.0.min.js">
 </script>
 <meta name="viewport" content="width=device-width, initial-scale=1">
</head>

<body>

 <div data-role="page" id="main">

   <div data-role="header">
     <h1>HTML5 and APIs</h1>
   </div>

   <div data-role="content">
      <ul data-role="listview">
          <li>Offline Access
          <li>Geolocation API
          <li>Canvas
          <li>Offline Storage
          <li>New semantic tags
      </ul>
   </div>

  </div>

 </body>
</html>
A typical list view renders rows nicely for touch devices
Figure 4-1. A typical list view renders rows nicely for touch devices

jQuery Mobile renders lists optimized for touch usage, as you can see in the default row height used by the framework. Every list item automatically fits the whole width of the page, a typical UI pattern for touch mobile devices. (If we have a long list, we can use fixed toolbars.)

Note

Remember that jQuery Mobile works on the client side. The document with the list can be generated dynamically with any server-side platform, such as PHP, Java, ASP.NET, or Ruby without any issue.

We can also use ordered lists with the ol element. However, if we don’t define interactive rows with links, there will not be any rendering difference from ul, as we can see in Figure 4-2:

<!DOCTYPE html>
<html>

<head>
  <!-- Typical jQuery Mobile header goes here -->
</head>

<body>

 <div data-role="page" id="main">

   <div data-role="header">
     <h1>Chapters</h1>
   </div>

   <div data-role="content">
      <ol data-role="listview">
          <li>The Mobile Jungle
          <li>Mobile Browsing
          <li>Architecture and Design
          <li>Setting up your environment
          <li>Markups and Standards
          <li>Coding Markup
          <li>CSS for Mobile Browsers
          <li>JavaScript Mobile
          <li>Ajax, RIA and HTML5
          <li>Server-Side Browser Detection
          <li>Geolocation and Maps
          <li>Widgets and Offline webapps
          <li>Testing, Debugging and Performance
          <li>Distribution and Social Web 2.0
      </ol>
   </div>

  </div>

 </body>
</html>

This sample shows how jQuery Mobile renders list rows. If the text doesn’t fit on a single line, the framework will automatically resize that row.

An ordered list is rendered the same as an unordered list, unless we define an interactive list
Figure 4-2. An ordered list is rendered the same as an unordered list, unless we define an interactive list

Note

HTML5 does not use XML syntax; therefore it’s not necessary to close all tags, like the element li. Of course, you can close them if you feel more comfortable (for example, if you are a developer like me; a nonclosing li hurts my eyes).

Full-Page Lists Versus Inset Lists

By default, lists are in a full-page mode. That means that the list covers the whole page contents, as in Figures 4-1 and 4-2. However, on some projects, it can be useful to have lists mixed up with other HTML content. For that purpose, jQuery Mobile offers inline lists. To define them, just add data-inset="true" to the ul or ol elements:

<ol data-role="listview" data-inset="true">
    <!-- item rows -->
</ol>

In Figure 4-3 we can see how our previous samples are rendered using the inline attribute. As we can see, the table has a slightly different design, with more padding sharing space with other content inside the same page. It also adds nice rounded corners and other CSS3 effects.

An inset table has a very different UI and it can share the page with other content, including other lists
Figure 4-3. An inset table has a very different UI and it can share the page with other content, including other lists

Note

With lists, we can define color swatches via data-theme on the ul element and also on every li element.

With inline lists we can also design a page with multiple tables inside with optional HTML content between them.

Visual Separators

You can use separators to divide a single list into row groupings with their own titles, as shown in Figure 4-4. It’s a common pattern on mobile operating systems, such as iOS on iPhone and iPad. To do this in jQuery Mobile, we can just use a new role available for li elements: data-role="list-divider".

Warning

Note that list dividers are just standard li elements with a different role, and they are at the same level as the normal row on the DOM tree.

We can divide the list elements into groups using this technique, such as A-Z groups if we are listing alphabetical ordered data or any other classification we want to make. Remember we can change the color swatch to highlight each divider.

Let’s run a simple example:

<!DOCTYPE html>
<html>

<head>
  <!-- Typical jQuery Mobile header goes here -->
</head>

<body>

 <div data-role="page" id="main">

   <div data-role="header">
     <h1>World Cup</h1>
   </div>

   <div data-role="content">
      <ul data-role="listview">
          <li data-role="list-divider">Group A
          <li>Argentina
          <li>Nigeria
          <li>England
          <li>Japan
          <li data-role="list-divider">Group B
          <li>United States
          <li>Mexico
          <li>Korea
          <li>Greece
          <li data-role="list-divider">Group C
          <li>Germany
          <li>Finland
          <li>Chile
          <li>South Africa
      </ul>
   </div>

  </div>

 </body>
</html>
Here we can see how the row separators render on the list
Figure 4-4. Here we can see how the row separators render on the list

Warning

If we are populating the list from client-side code, as in JavaScript, we must call a refresh method after doing so, so the framework can take changes and render them properly. We will cover these techniques later, but for now, if you have only one list on a page with id page1, the jQuery code will look like $("#page1 ul").listview("refresh").

In Figure 4-4, we can see how list dividers work over lists.

Interactive Rows

Lists become more powerful when we combine them with touch interaction.

If a list element contains an a element, it will convert that row in an interactive one for touch and/or cursor navigation. One great feature of jQuery Mobile is that the whole row will be interactive automatically for touch no matter where the link is placed inside the row. Meaning the user doesn’t need to tap only in the link’s text area. She can tap on any pixel in the row.

Note

An interactive row has a different height than a read-only one. This different design is optimized for touch interaction, as the touch area needs to be large enough to avoid errors. The row text also has a larger font size. In iOS-based devices, 44 pixels is the recommended height for most common controls. Other touch devices use similar sizes.

The framework automatically adds a nice arrow at the right side of the row giving the user a hint that the row is touchable, as seen in Figure 4-5. This icon can be changed using data-icon, as we will see in a minute.

On the same list, we can mix interactive rows with read-only rows. However, the most typical UI design is to have full-interactive or full-read-only lists.

In the following sample, shown in Figure 4-5, we can see interactive rows in action:

<!DOCTYPE html>
<html>

<head>
  <!-- Typical jQuery Mobile header goes here -->
</head>

<body>

 <div data-role="page" id="main">

   <div data-role="header">
     <h1>Interactive</h1>
   </div>

   <div data-role="content">
      <ul data-role="listview">
          <li><a href="#page2">Internal Page link</a>
          <li><a href="other.html">External Page link</a>
          <li><a href="http://www.mobilexweb.com">Absolute external link</a>

          <li><a href="tel:+13051010200">Call to a phone number using a link</a>
          <li><a href="javascript:alert('Hi!')">JavaScript link</a>
      </ul>
   </div>

  </div>

 </body>
</html>
Interactive rows are just hyperlinks inside list elements that automatically are clickable and touchable
Figure 4-5. Interactive rows are just hyperlinks inside list elements that automatically are clickable and touchable

As we can see in Figure 4-5, when we are working with interactive rows, jQuery Mobile tries to maintain rows of the same height. Therefore, when the row’s title doesn’t fit in one line, like the fourth row’s title, jQuery Mobile will crop the text, adding an ellipsis at the end on CSS3-compatible devices. Keep the length of a row’s text to a minimum if you don’t have a detail page with the full text.

The a element must be inside the li tag, and there is no obligation to insert the row title as the content of the link. We can just leave the link empty and it will work anyway:

<li><a href="#page2"> Internal Page link </a>

On some devices with cursor or focus navigation, such as BlackBerry or Android, the user may choose to navigate with the keyboard keys or a trackball. Firing a row (using some OK key or pressing the trackball) will fire the link inside the list element. In Figure 4-6, you can see how this works on Android devices with a border focus shown typically in orange by the browser on the selected row.

On focus-based browsers, interactive lists can be browsed using cursor keys or a trackball
Figure 4-6. On focus-based browsers, interactive lists can be browsed using cursor keys or a trackball

Using interactive lists is the preferred way to create links in a page, instead of using just a tags alone, because they are optimized for touch and cursor-based navigation.

When the user taps an interactive row that generates a page redirection action inside the framework, the row becomes selected while the new page is being transitioned or loaded from the network. A selected row has a different color scheme, as seen in Figure 4-7.

When a interactive row is selected, the framework changes its color scheme to a highlight background, light-blue on the default theme
Figure 4-7. When a interactive row is selected, the framework changes its color scheme to a highlight background, light-blue on the default theme

We can change the default interactive row’s icon using data-icon on the li element, for example:

<li data-icon="info"><a href="#moreinfo">More information</a></li>

If we want to remove the icon on an interactive row, we can use the special false value on data-icon:

<li data-icon="false"><a href="#page2">No icon interactive row</a></li>

Nested Lists

Nested lists are a great feature of jQuery Mobile. If you have any hierarchical structure or navigation that you want to show in different pages, as in continents countries cities, you can use a nested list.

A nested list is just a list view (a list with the role specified) inside an item of another list view. For example, we can use a ul inside an li of another ul. jQuery Mobile will generate an implicit page for every nested list as if it were created by us explicitly and will make the link between levels automatically.

A nested list will be rendered with a different theme to provide visual reference that it is a second-level list. Of course, we can define theming explicitly with data-theme as we are going to see later.

Then, we have different levels of navigation automatically creating only one page. After loading, jQuery Mobile will show only items from the first level, and every item with a list inside it will become an interactive row. If the user selects that row, a transition to a new page will execute showing the next level list view with the back action to the previous level.

There is no limit in the quantity of levels a nested list can have. However, if you have too many levels and items, it’s a good idea to use different pages to reduce DOM and initial loading. Nested lists are only recommended for specific situations. Don’t create your whole site as a nested list.

Of course, we can mix nested lists with normal interactive rows. Therefore we can have a first level list with some items linked to other documents or pages, and other items with nested lists.

It’s important to add text to the li in addition to the ul or ol because the framework needs to show a title for the interactive item in the implicit page that is created.

Therefore, a typical nested list will look like:

<li>
    Item title
    <ul data-role="listview">
        <!-- Nested list items -->
    </ul>

Let’s create a sample, as shown in Figure 4-8:

<!DOCTYPE html>
<html>

<head>
  <!-- Typical jQuery Mobile header goes here -->
</head>

<body>

 <div data-role="page" id="main">

   <div data-role="header">
     <h1>Training</h1>
   </div>

   <div data-role="content">
      <ul data-role="listview">
          <li><a href="order.html">Order Now!</a>

          <li>Cities available
                <ul data-role="listview">
                      <li>Boston
                      <li>New York
                      <li>Miami
                      <li>San Francisco
                      <li>San Jose
                </ul>

          <li>Topics
                <ul data-role="listview">
                      <li>Intro to Mobile Web
                            <ul data-role="listview">
                                <li>WML and other oldies
                                <li>XHTML MP
                                <li>HTML 4.01
                                <li>HTML5
                            </ul>
                      <li>Mobile Browsers
                            <ul data-role="listview">
                                <li>Safari for iOS
                                <li>Android Browser
                                <li>Firefox for Mobile
                                <li>Opera
                            </ul>
                      <li>Tablet Browsers
                      <li>Using jQuery
                </ul>

          <li>Promotions
                <ul data-role="listview">
                      <li>10% off before May
                      <li><a href="promo3x2.html">3x2</a>
                      <li>10% off to subscribers
                </ul>

      </ul>
   </div>

  </div>

 </body>
</html>

Warning

In nested tables, jQuery Mobile will automatically use the row text as the title for the newly generated page, so be aware that you need to keep your text as simple and short as possible to fit in the title area.

Nested lists offer navigation similar to having different pages without creating new pages
Figure 4-8. Nested lists offer navigation similar to having different pages without creating new pages

In Figure 4-8 we can see all the navigation and pages that we get when using a nested list without special effort.

Note

With some jQuery Mobile hacks, we can create links to the automatically generated pages in a nested list manipulating the URL hash. However, if we need to do so, it might be better to have an explicit page created instead of a nested list.

Split Button Lists

Sometimes it’s useful if we can have two possible interactive actions active on the same row. The most common scenario is to have a detail action and also an edit action.

For example, if we list contact names on a table, we can offer two possible actions: view details and edit. For that purpose, jQuery Mobile uses what it is called a split row. If a list item, li, has two hyperlinks (a element), it will be automatically treated as an split row.

A split row allow us to have two active zones per row, one for the typical action and one defined by a separate icon at the right
Figure 4-9. A split row allow us to have two active zones per row, one for the typical action and one defined by a separate icon at the right

As we can see in Figure 4-9, the row is split in two parts: left and right. The first link in the DOM will be used as the first action, active in the left side of the row. The second link will be used as the alternate action, activated on the right side of the row.

The second link action doesn’t need any text inside the link. In fact, the first link action doesn’t either. We can leave the a link without contents, and it will be applied to the whole row.

Note

Following iOS user interface guidelines, the first action should be used for details and the second action should be used for edit. However, that is not an obligation.

By default, jQuery Mobile will use a bordered arrow icon for the right button (the second action) a little different than the one for standard interactive rows.

If we want to define a different theme for the right split icon, we can do it using data-split-theme over the ul tag.

Let’s take a look at a sample, shown in Figure 4-10:

<!DOCTYPE html>
 <html>

 <head>
   <!-- Typical jQuery Mobile header goes here -->
 </head>

 <body>

  <div data-role="page" id="main">

    <div data-role="header">
      <h1>Your Friends</h1>
    </div>

    <div data-role="content">
       <ul data-role="listview">
           <li><a href="details/bill">Bill Gates</a>
               <a href="edit/bill"></a>

           <li><a href="details/steve">Steve Jobs</a>
               <a href="edit/steve"></a>

           <li><a href="details/mark">Mark Zuckerberg</a>
               <a href="edit/mark"></a>

           <li><a href="details/larry">Larry Page</a>
               <a href="edit/larry"></a>
       </ul>
    </div>

   </div>


  </body>
 </html>
Every zone has its own selected state, as we can see here
Figure 4-10. Every zone has its own selected state, as we can see here

We can change the icon for the second action using the modifier data-split-icon—applied to the list itself (ul or ol element) and not to the list item (li element).

The list view uses the same icon set as for buttons (as we are going to see in the next chapters), but with the addition of a rounded border for a visual difference from normal buttons.

The possible icons we can use up to jQuery Mobile 1.0 are shown in Table 3-1.

Note

We can provide our own icon set using only one image and applying CSS Sprites, like the ones included in the framework.

Managing row importance

If we want some or all rows to be more important than typical ones, we can insert the row’s title inside any hx tag, such as h2 or h3. When we do that, that row will grow in height.

If we want a row to be less important (maybe for a not-so-frequent action), we should enclose the row’s title in a p tag to reduce the row’s height.

In later chapters we will see how to customize list views and rows in a more precise way.

Ordered Interactive Lists

Previously in this chapter, we talked about using ol for defining our list views instead of ul. We’ve also realized that using ol on read-only lists has no effect on the rendering. That is definitely different when we have interactive rows.

First, one important requirement: all the rows must be interactive for this list to work. Then, we can use ol and our links will be numbered automatically, as we can see in Figure 4-11.

If we define a listview role in a ol element with interactive rows, we’ll get this ordered UI
Figure 4-11. If we define a listview role in a ol element with interactive rows, we’ll get this ordered UI

Using Images

In each row we can define one image to graphically identify the item. There are two different kinds of images we can add to every row: icons and thumbnails.

Row Icons

A row icon is an image shown at the left side of the row’s title. Don’t confuse the row icon with the right arrow on interactive rows or with the split rows’s icon.

An icon is a 16×16-pixel image inside the li element, with the class ui-li-icon defined. For example:

<li>
   <img src="/icons/email.png" class="ul-li-icon">
   Send by e-mail

Icons are usually used for action lists, for example, for a list showing multiple actions we can do with a record (delete, edit, share by email, share in a social network, etc.).

Thumbnails

A thumbnail is an 80×80-pixel image that is also positioned at the left of the text. They are preferred to icons when we are showing photos, pictures, or other graphical information attached to each item.

Thumbnails are usually used for lists showing database records, such as friends, books, DVDs, cities, etc.

A thumbnail is defined as an image inside the list item. It doesn’t need any special class defined:

<li>
   <img src="/thumb/washington.png">
   George Washington

Let’s see icons and thumbnails in action in two inset lists at Figure 4-12.

A picture worth millions; that is why we can add icons and thumbnails to every list row
Figure 4-12. A picture worth millions; that is why we can add icons and thumbnails to every list row

Aside Content

Up to now, every list we’ve designed has only one column for text content. We can add a thumbnail or an icon but only one text column. We can add a second-level column to every row for supplemental information we want to show.

To do so, we can use any HTML element with a class of ui-li-aside, such as a span or div element.

Let’s create a sample showing a price as the aside content (Figure 4-13):

<!DOCTYPE html>
 <html>

 <head>
   <!-- Typical jQuery Mobile header goes here -->

 </head>

 <body>

    <div data-role="header">
      <h1>Order online</h1>
    </div>

    <div data-role="content">
       <ul data-role="listview">
           <li><a href="buy.html">Soda</a>
               <span class="ui-li-aside">$1.00</span>
           <li><a href="buy.html">Sandwich</a>
               <span class="ui-li-aside">$3.20</span>
           <li><a href="buy.html">Ice cream</a>
               <span class="ui-li-aside">$1.50</span>
       </ul>
    </div>

   </div>

 </body>
 </html>
With aside content, we can show more information about a row without using a new page
Figure 4-13. With aside content, we can show more information about a row without using a new page

Title and Description

If we want to show both a title and a description as part of the row, we can do it by using some header element hx tag for the title and a p element for the description text. This is not rendered as a second column but as shown in Figure 4-14.

Of course, you can mix title and description with aside content and with icons or thumbnails in the same row.

If we need to provide long content aside from the title, the best solution is to show a title and a description instead of aside content.
Figure 4-14. If we need to provide long content aside from the title, the best solution is to show a title and a description instead of aside content.

Using Count Bubbles

A count bubble is a circle with a number inside rendered at the right of the row usually showing how many items are in there on interactive rows. It can be used to show unread elements, unfinished tasks, or any other numeric information in a very simple way.

Warning

There is no limitation to a numeric value for the count bubble. However, using text is discouraged because the space available is optimized for numeric values. For text, use aside content or description.

Just use any element, such as a span tag, with a class of ui-li-count inside a list row and that’s all. For example:

<li><a href="inbox.html">Inbox</a>
    <span class="ui-li-count">86</span>

In Figure 4-15 we can see how a count bubble is rendered on an interactive list. We can define the count bubble’s color swatch via data-count-theme on the ul element so we can change the default white background color.

An interactive lists with count bubbles
Figure 4-15. An interactive lists with count bubbles

I’ve left the best part for the last. Leave your book for a moment. If you are reading this book in any digital format, leave the reader or your browser. Go and take any of the list view samples we’ve done in this chapter.

Search for the ul or ol element and add data-filter="true", test it and then go back to the book.

The magic of jQuery Mobile has happened. When adding this simple attribute, a search box will be attached automatically at the top the list (full page or inset) and it works!

This feature will filter our list elements based on the user’s typing. The search text box looks very nice (as you can see in Figure 4-16), with a search icon at the left side, a watermark hint text, rounded corners, and a clear button at the right side.

Again, for this to work, just use the following code. Please go now to this book’s website to grab the source code to copy and paste. Typing it will be very hard for you:

<ul data-role="listview" data-filter="true">
  <!-- list rows -->
</ul>

We can customize the placeholder text using data-filter-placeholder, for example:

<ul data-role="listview" data-filter="true" data-filter-placeholder=
    "Search contacts...">
  <!-- list rows -->
</ul>

If we want to customize the search bar’s color swatch, we can use the data-filter-theme attribute.

Search filters are a magic solution that adds a filtering system without any code
Figure 4-16. Search filters are a magic solution that adds a filtering system without any code

List Views Cheat Sheet

We’ve covered many features of list views in the last few pages. In Figure 4-17 you will find a quick cheat sheet to understand how to render your list views using HTML markup.

All the list view possibilities in one diagram
Figure 4-17. All the list view possibilities in one diagram

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required