344 jquery mobile

www.it-ebooks.info


www.it-ebooks.info


Download from Wow! eBook <www.wowebook.com>

www.it-ebooks.info

jQuery Mobile


www.it-ebooks.info


www.it-ebooks.info

jQuery Mobile

Jon Reid

Beijing • Cambridge • Farnham • Köln • Sebastopol • Tokyo


www.it-ebooks.info

jQuery Mobile
by Jon Reid
Copyright © 2011 Jonathan Reid. All rights reserved.
Printed in the United States of America.

Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472.
O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions
are also available for most titles (). For more information, contact our
corporate/institutional sales department: (800) 998-9938 or

Editor: Mary Treseler
Production Editor: Jasmine Perez
Proofreader: Jasmine Perez

Cover Designer: Karen Montgomery
Interior Designer: David Futato
Illustrator: Robert Romano

Printing History:
June 2011:

First Edition.

Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of
O’Reilly Media, Inc. jQuery Mobile, the image of the squirrel tree toad, and related trade dress are
trademarks of O’Reilly Media, Inc.
Many of the designations used by manufacturers and sellers to distinguish their products are claimed as
trademarks. Where those designations appear in this book, and O’Reilly Media, Inc. was aware of a
trademark claim, the designations have been printed in caps or initial caps.
While every precaution has been taken in the preparation of this book, the publisher and authors assume
no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

ISBN: 978-1-449-30668-7
[LSI]
1307713150

www.it-ebooks.info

Table of Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
1. Meet jQuery Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Overview of the jQuery Mobile Library
How jQuery Mobile Works
Create Your First jQuery Mobile Application
Under The Hood: the jqmData() Custom Selector

1
2
2
7

2. Application Structure and Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Pages
Internal Pages
External Pages
Under The Hood: Page Initialization in jQuery Mobile
Page Hide and Show Events
Dialogs
Navigation and History
Transitions
Under The Hood: Animations in a jQuery Mobile Application

9

10
12
15
17
20
20
22
23

3. Page Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Under The Hood: jQuery Plug-ins and Widgets
List Views
Basic List View
Advanced List Views
Under The Hood: Updating a List View
Toolbars
Navigation Bars
Positioning the Header and Footer
Buttons
Button Control Groups
Button Icons

25
26
26
29
39
39
39
43

44
46
47

v


www.it-ebooks.info

Form Elements
Accessing Form Elements with JavaScript
Checkboxes and Radio Buttons
Flip Toggle
Input Fields and Textareas
Search Fields
Select Menus
Sliders
Layout Grids

49
49
50
52
53
54
55
59
61

4. Theming jQuery Mobile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Themes and Swatches
Under The Hood: Customizing a Swatch
Theming List View Elements

65
74
78

5. jQuery Mobile API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
jQuery Mobile Methods
changePage
pageLoading
silentScroll
addResolutionBreakpoints
Events
Touch Events
Initialization Events
Page Hide and Show Events
Scroll Events
Orientation Change Events
Responsive Layout API
CSS Selectors
Configuring jQuery Mobile
Available Options
Changing an Option via mobileinit
Under The Hood: Namespacing Data Attributes

79
79
80

80
80
81
81
83
84
85
85
85
85
88
88
89
90

6. jQuery Mobile in Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Application Pages
Initializing the Application
The initMainPage Method
The initSettings Method
The initDetailPage Method
Error Dialog
jqmTweet Take One
Improving the Interface
vi | Table of Contents

93
97
97
102

103
103
104
106


www.it-ebooks.info

CSS Tweaks
Interaction Tweaks
Overall Approach

106
106
111

Table of Contents | vii


www.it-ebooks.info


www.it-ebooks.info

Preface

Introduction
Mobile applications come in two basic flavors: native applications, which are compiled
programs that run natively on the device, and mobile web applications, which run
inside a web browser on the device.

Native applications get almost all of the press these days, especially given the financial
success of the iTunes App Store and the Android Market. And with good reason, as
native applications have many advantages: they are fast, have access to all of the power
of the platform they are built for, and so forth. However, native applications suffer from
one important limitation: they are not portable. If you want to make your application
available on multiple platforms, you either have to write it in multiple languages
(resulting in multiple code bases to maintain) or use a platform abstraction layer like
Titanium or PhoneGap.
Mobile web applications, on the other hand, are created in HTML, CSS, and JavaScript,
and run in the web browser on the mobile device. This means one code base to maintain,
but mobile web applications still need to account for variations in web browsers across
platforms.
Enter jQuery Mobile. Based on the popular jQuery JavaScript library, jQuery Mobile
is designed to create mobile web applications that function on a broad range of devices.
With jQuery Mobile, it is possible to quickly create mobile web applications that look
and behave consistently across all supported devices, and that have advanced user
interface capabilities. jQuery Mobile gives the developer a standard set of layouts, user
interface widgets, and interactions, as well as a rich API for applying and extending
them.
jQuery Mobile is not yet in production—as of this writing, it is in its Alpha 4 release,
with the beta coming soon.
Even so, the library already has a broad set of features and is remarkably stable. In fact,
I have already used it in one production project with great success, and if you review
posts on the jQuery Mobile forums, you’ll see that there are many people using jQuery

ix


www.it-ebooks.info

Mobile in production. As jQuery Mobile advances, we hope to update this ebook to
cover new features and provide new tips and techniques.

What This Book Covers
This book covers how the jQuery Mobile library works, and how to use it to create
mobile web applications. While I was writing this book I was engaged in a project in
which I was using jQuery Mobile to create a mobile web application. This gave me a
unique insight into how to use jQuery Mobile in a production environment, so this
book takes a practical approach for using the library and focuses on example code and
screenshots. In addition, throughout the book there are “Under The Hood” sections
where I explore a topic in more detail: page initialization, using swipe events to trigger
page transitions, animation in a jQuery Mobile application, and so forth.
In Chapter 1, we will provide a high-level overview of jQuery Mobile, how it works,
and how to use it. If you follow the examples in the chapter, at the end of the chapter
you will have built your first jQuery Mobile application. It won’t do much, but it will
show how easy it is to set up a jQuery Mobile application and introduce you to some
important jQuery Mobile concepts.
Chapter 2 covers paging and navigation in jQuery Mobile, including dialogs, AJAX
content, and history.
In Chapter 3, we will cover the UI elements that jQuery Mobile can create: toolbars,
buttons, lists, form elements, and layout grids.
In Chapter 4, we will cover the jQuery Mobile theme framework, how to use it, and
how to customize it.
In Chapter 5, we will take a look at the new events that jQuery Mobile creates, the
methods it exposes, and how to customize jQuery Mobile for your own applications.
Chapter 6 is where we will put everything together and build an actual mobile application: jqmTweet. We’ll walk through how to approach building a mobile application
with jQuery Mobile from start to finish.

What You Need To Know
This book assumes you are already familiar with the jQuery JavaScript library. You

should be able to create jQuery selectors and apply jQuery methods to them.
This book assumes you are familiar with HTML markup and Cascading Style Sheets.
Throughout the code examples, we will be using HTML 5 and CSS 3, and employing
industry best practices like semantic markup and progressive enhancement.
This book also assumes that you have a basic familiarity with mobile web browsers.
Though jQuery Mobile aims to provide a cross-platform API, it is still necessary for a
mobile web developer to understand mobile browsers and their capabilities.

x | Preface


Download from Wow! eBook <www.wowebook.com>

www.it-ebooks.info

Finally, this book assumes you are familiar with the technologies of the web: HTTP,
clients and servers, security, etc.

Conventions Used In This Book
The following typographical conventions are used in this book:
Italic
Indicates a term, URL, email address, or filenames or extensions.
Constant Width

Used for code examples and for code elements such as variable names, function
names, keywords, etc. that are included in regular paragraphs.
Constant width italic

Shows text that should be replaced with user-supplied values or by values determined by context.
This signifies a tip, suggestion, or note of interest.

This indicates a warning or caution: a bug in the library, a common
problem, etc.

Using Code Examples
This book is here to help you get your job done. In general, you may use the code in
this book in your programs and documentation. You do not need to contact us for
permission unless you’re reproducing a significant portion of the code. For example,
writing a program that uses several chunks of code from this book does not require
permission. Selling or distributing a CD-ROM of examples from O’Reilly books does
require permission. Answering a question by citing this book and quoting example
code does not require permission. Incorporating a significant amount of example code
from this book into your product’s documentation does require permission.
We appreciate, but do not require, attribution. An attribution usually includes the title,
author, publisher, and ISBN. For example: “jQuery Mobile by Jon Reid (O’Reilly).
Copyright 2011 Jonathan Reid, 978-1-449-30668-7.”
If you feel your use of code examples falls outside fair use or the permission given above,
feel free to contact us at

Preface | xi


www.it-ebooks.info

Safari® Books Online
Safari Books Online is an on-demand digital library that lets you easily
search over 7,500 technology and creative reference books and videos to
find the answers you need quickly.
With a subscription, you can read any page and watch any video from our library online.
Read books on your cell phone and mobile devices. Access new titles before they are

available for print, and get exclusive access to manuscripts in development and post
feedback for the authors. Copy and paste code samples, organize your favorites, download chapters, bookmark key sections, create notes, print out pages, and benefit from
tons of other time-saving features.
O’Reilly Media has uploaded this book to the Safari Books Online service. To have full
digital access to this book and others on similar topics from O’Reilly and other publishers, sign up for free at .

How to Contact Us
Please address comments and questions concerning this book to the publisher:
O’Reilly Media, Inc.
1005 Gravenstein Highway North
Sebastopol, CA 95472
800-998-9938 (in the United States or Canada)
707-829-0515 (international or local)
707-829-0104 (fax)
We have a web page for this book, where we list errata, examples, and any additional
information. You can access this page at:
/>To comment or ask technical questions about this book, send email to:

For more information about our books, courses, conferences, and news, see our website
at .
Find us on Facebook: />Follow us on Twitter: />Watch us on YouTube: />
xii | Preface


www.it-ebooks.info

Acknowledgments
I’d like to thank RJ Owen for volunteering to do the technical review of this book. His
honesty and encouragement helped make this book a success.
I also want to thank Juan Sanchez for providing suggestions for the “Under The Hood”

sections in the book.
The HTML development team at EffectiveUI patiently listened to me rave about jQuery
Mobile and obsess about this book: Aaron Congleton, Ryan McGinty, Kevin Bauman,
Shane Church, Tony Walt, and George Robison. Thanks, guys.

Preface | xiii


www.it-ebooks.info


www.it-ebooks.info

CHAPTER 1

Meet jQuery Mobile

jQuery Mobile is a set of jQuery plug-ins and widgets that aim to provide a crossplatform API for creating mobile web applications. In terms of code implementation,
jQuery Mobile is very similar to jQuery UI, but while jQuery UI is focused on desktop
applications, jQuery Mobile is built with mobile devices in mind.
As of this writing, jQuery Mobile is still in its Alpha 4 release, with beta just around
the corner. There are still plenty of issues that are being fixed, but the jQuery Mobile
development team has said that they consider the library to be feature-complete for
their 1.0 release. Although the documentation is sparse, especially compared to the
extensive documentation for the jQuery project itself, the forums are very active.
Even so, many people are already using jQuery Mobile in production, which is a
testament not only to the stability and quality of the library, but of how easy it is to use.

Overview of the jQuery Mobile Library
As of this writing, jQuery Mobile consists of four files: a JavaScript file, a CSS file, and

two PNG graphic sprites.
The JavaScript file is meant to be loaded after the base jQuery library. This script file
performs various tasks, like creating widgets, applying event listeners, and enabling the
API.
jQuery Mobile also includes a Cascading Style Sheet which specifies layout and
appearance of jQuery Mobile page elements. The Style Sheet also specifies transitions
and animations with CSS3 transforms.
Finally, jQuery Mobile includes a small set of graphics for user interface elements. These
are simple, standardized icons for navigation.
You can download the entire jQuery Mobile package (the JavaScript library, the CSS,
and the graphics) or you can access them through the project’s CDN. See the jQuery
Mobile project download page for specifics. In the examples for this book, we will be
using the CDN.
1


www.it-ebooks.info

How jQuery Mobile Works
jQuery Mobile uses HTML 5 and CSS 3 features to enhance basic HTML markup to
create a consistent mobile experience across supported platforms. jQuery Mobile
makes heavy use of the HTML 5 specification for custom data- attributes (available for
review at />-data-with-the-data-attributes). Using this method, it is possible to embed data into
valid HTML 5 markup. jQuery Mobile has a large vocabulary of data- attributes.
Upon initialization, jQuery Mobile selects elements based on their data- attributes and
enhances them by inserting extra markup, adding new CSS classes, and applying event
handlers. This enables you to quickly write basic semantic markup and leave it to
jQuery Mobile to transform your simple markup into complex user interface elements.
It’s actually an interesting exercise to see what jQuery Mobile adds to
your basic markup. To do this, you will need the ability to view source

both before and after JavaScript has been applied to a page—in most
browsers, the “view source” menu option will only show you the
unenhanced source. However, most browsers have “view generated
source” plug-ins available, and the ability to view generated source is
built into some browser-based web development toolbars.

Create Your First jQuery Mobile Application
The best way to understand jQuery Mobile is to dive right in. Begin by creating a simple
HTML 5 page that includes the jQuery and jQuery Mobile libraries, as shown in
Example 1-1.
Example 1-1. Basic HTML5 page for a jQuery Mobile application
<!DOCTYPE html>
<html>
<head>
<title>jQuery Mobile Application</title>
<link rel="stylesheet" href=" />jquery.mobile-1.0a4.1.min.css" />
<script src=" /><script src=" /></script>
</head>
<body>
</body>
</html>

2 | Chapter 1: Meet jQuery Mobile


www.it-ebooks.info

This includes everything you need to start building a jQuery Mobile application.
Next, we need to include some content. Content should be marked up semantically,
and since we’re using HTML 5, we have access to all of the new tags like header, footer,

section, nav, etc. We can mark up our content using those tags, or we simply block off
our content using div tags.
For our first example, we want to create a page in our application that is a self-contained
section, with a header, content area, and footer. (We’ll discuss the details of pages and
views in jQuery Mobile in the next chapter. For now, we’ll just focus on the simplest
case.) Using div-based markup, we would create something like what is shown in
Example 1-2.
Example 1-2. Old and busted: div-based markup
<div class="section" id="page1">
<div class="header">

jQuery Mobile

</div>
<div class="content">

First page!

</div>
<div class="footer">

O'Reilly

</div>
</div>

Or we can mark up the same content using the HTML 5 tags section, header, and
footer, as shown in Example 1-3.
Example 1-3. New hotness: HTML 5 markup
<section id="page1">
<header>

jQuery Mobile

</header>
<div class="content">

First page!

</div>
<footer>

O'Reilly

</footer>
</section>

jQuery Mobile will work with either markup style, though as we move forward in this
book, we will use the HTML 5 markup.
jQuery Mobile doesn’t need specific markup, but it does need us to indicate the roles

of the content areas somehow. To do this, jQuery Mobile uses a custom data- attribute:
data-role. Valid data-role values include page, header, content, and footer.
This is our first encounter with a custom data- attribute. jQuery Mobile uses them
extensively to designate functionality, layout, and behaviors. We’ll learn more about
them in later chapters, so for right now we’ll just focus on the data-role attribute.
Applying the appropriate data-role attributes, our HTML 5 markup would be written
as shown in Example 1-4.

Create Your First jQuery Mobile Application | 3


www.it-ebooks.info

Example 1-4. jQuery Mobile data-role attributes applied to HTML 5 markup
<section id="page1" data-role="page">
<header data-role="header">

jQuery Mobile

</header>
<div class="content" data-role="content">

First page!

</div>
<footer data-role="footer">

O'Reilly

</footer>
</section>

That is all you need to do to create an application in jQuery Mobile. It will do all the
rest for you.
To view your new web application, you can run it locally in an HTML 5 capable browser
(such as Safari), as shown in Figure 1-1.

Figure 1-1. First page in Safari

This will give you an idea of what it will look like and how it will perform, but to really

test the application you will need to view it in a mobile device.
You can use various emulators that come with the platform application development
SDKs, but the ideal way to test the application is to serve it via a web server and use a
mobile device to browse it. This will give you the best feel for how the application
behaves.
4 | Chapter 1: Meet jQuery Mobile


www.it-ebooks.info

Setting yourself up to serve your content locally is actually quite easy.
My favorite drop-in tool is XAMPP, available at che
friends.org/en/xampp.html. It is available for Windows, OS X, Linux,
and Solaris, and has great step-by-step tutorials and how-to guides.

Throughout this book, we will be using screen shots from an iPhone, and our current
application is shown in Figure 1-2.

Figure 1-2. First page in iPhone

Adding another page is a simple matter of copying and pasting our code and changing
the id of the containing section and updating the content to reflect a new page, as
shown in Example 1-5.
Example 1-5. Adding a second page to the sample application
<section id="page2" data-role="page">
<header data-role="header">

jQuery Mobile

</header>
<div class="content" data-role="content">

Second page!

</div>
<footer data-role="footer">

O'Reilly

</footer>

</section>

Create Your First jQuery Mobile Application | 5


www.it-ebooks.info

Navigation between pages is simple: just add a link to your content area in the first
page of the application, as shown in Example 1-6.
Example 1-6. Adding a link to second page
<div class="content" data-role="content">

First page!

<a href="#page2">Go to the second page!</a>

</div>

Now when you refresh the application, you will see a link to tap, as shown in Figure 1-3.

Figure 1-3. Link to next page

Tapping the link will transition to the next screen. jQuery Mobile will automatically
handle the page transition animation, and will automatically provide a back button in
the header.
Tapping on the back button will return you to the previous page, and again jQuery
Mobile will automatically handle the page transition.
There you have it, your first jQuery Mobile application. It doesn’t do much, but it
should give you some insight into the simplicity of the framework. All you have to do
6 | Chapter 1: Meet jQuery Mobile


Download from Wow! eBook <www.wowebook.com>

www.it-ebooks.info

is mark up your content semantically and then designate roles, functionality, and
interactions using custom data- attributes. Then sit back and allow jQuery Mobile to
do all the work for you.

Under The Hood: the jqmData() Custom Selector
jQuery Mobile has a new custom selector that it uses to select elements with dataattributes. You’re probably already familiar with jQuery’s other built in custom selectors, which include :has(), :contains(), :eq(), etc. These selectors can be used either
to directly select elements (e.g. $("div:contains('foo')")) or they can be used to filter
other selectors (e.g. $("div").contains('foo')).
You can select all elements with a data-role="page" attribute using the standard jQuery
selector $("[data-role='page']"). This works fine, but since jQuery Mobile relies so
heavily on custom data- attributes, it made sense to build a custom selector: jqmData().
To use jqmData() to select all elements with a data-role="page", you would use
$(":jqmData(role='page')"). To select all elements with any custom data- attribute
within those selected pages, you could use $(":jqmData(role='page')").jqmData(role).
The jqmData() selector also automatically handles namespacing. Since jQuery Mobile
relies so heavily on data attributes, you should be able to apply a namespace to them
to avoid conflicts with other data attributes that won’t be used by jQuery Mobile. (For
example, instead of data-role="page", it could use data-namespace-role="page" where
namespace- is a configurable string.) By default, jQuery Mobile does not apply a namespace, but it can be configured to do so using the $.mobile.ns configuration option (see
“Configuring jQuery Mobile” on page 88 in Chapter 5 for more information). If you
do configure a namespace, the jqmData() selector will automatically account for it.
There was an interesting discussion around adding the namespacing feature to jQuery
Mobile, which you can read over on the project’s GitHub at />jquery-mobile/issues/196.

Create Your First jQuery Mobile Application | 7

www.it-ebooks.info


www.it-ebooks.info

CHAPTER 2

Application Structure and Navigation

Pages
As we saw in our first example, jQuery Mobile designates pages using the data-role
attribute. Behind the scenes, jQuery Mobile selects elements based on this attribute
and progressively enhances them, adding CSS classes, any needed markup, and event
management. This may seem like a complicated way of handling things—why not
simply have regular pages linked like you ordinarily would?—but this methodology
gives jQuery Mobile several important features:
Page Transitions
By handling pages as separate content areas in one document, jQuery Mobile can
create smooth page transitions, resulting in an overall “application-like” look and
feel.
Navigation Management
jQuery Mobile can automatically handle page navigation, providing features like
back buttons and deep linking.
Efficiency
Since resources are all contained in one file, the browser does not have to access
the network over and over again, as it would with smaller individual files. This will
help mitigate application slowness and battery drain on the mobile device. The
trade-off is that for a large application there could be an appreciable download
time for a large HTML page with many individual jQuery Mobile page views.
However, once the file is downloaded and ready, the behavior will be much faster

and will not necessarily be dependent on network access.

9