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
ul HTML element) list
inside a page with at least one list item (
li HTML element) and
role defined as
listview using the HTML5 syntax
If you want to just show a bulleted or numbered list, you can always
ol HTML elements; just remember to not assign any
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:
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.)
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:
HTML5 does not use XML syntax; therefore it’s not necessary to close
all tags, like the element
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).
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
<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.
With lists, we can define color swatches via
data-theme on the
ul element and also on every
With inline lists we can also design a page with multiple tables inside with optional HTML content between them.
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
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>
If we are populating the list from client-side code, as in
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
In Figure 4-4, we can see how list dividers work over lists.
If a list element contains an
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.
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:
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.
<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.
Using interactive lists is the preferred way to create links in a
page, instead of using just
alone, because they are optimized for touch and cursor-based
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.
<li data-icon="info"><a href="#moreinfo">More information</a></li>
<li data-icon="false"><a href="#page2">No icon interactive row</a></li>
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
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.
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>
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.
In Figure 4-8 we can see all the navigation and pages that we get when using a nested list without special effort.
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.
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 (
it will be automatically treated as an split row.
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.
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.
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>
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.
We can provide our own icon set using only one image and applying CSS Sprites, like the ones included in the framework.
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
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.
<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.).
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
<li> <img src="/thumb/washington.png"> George Washington
Let’s see icons and thumbnails in action in two inset lists at Figure 4-12.
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.
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>
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
for the title and a
p element for the
description text. This is not rendered as a second column but as shown in
Of course, you can mix title and description with aside content and with icons or thumbnails in the same row.
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.
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.
<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.
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.
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>
<ul data-role="listview" data-filter="true" data-filter-placeholder= "Search contacts..."> <!-- list rows --> </ul>
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.