Introduction

jQuery Mobile is a superb framework for writing mobile web applications. Built on top of the popular jQuery and jQuery user interface (UI), jQuery Mobile is an effective, unified framework for writing your mobile web application. With jQuery Mobile you can ensure consistent look, feel, and behavior across different mobile platforms. The basic features of jQuery Mobile include:

• General simplicity and flexibility
  The framework is simple to use. You can:
  • Develop pages primarily using markup driven with minimal or no JavaScript.
  • Use advanced JavaScript and events.
  • Use a single HTML document with multiple embedded pages.
  • Break your application into multiple pages.
• Progressive enhancement and graceful degradation
  While jQuery Mobile leverages the latest HTML5, CSS 3, and JavaScript, not all mobile devices provide such support. jQuery Mobile philosophy is to support both high-end and less capable devices, such as those without JavaScript support, and still provide the best possible experience.
• Support for touch and other input methods
  jQuery Mobile provides support for different input methods and events: touch, mouse, and cursor focus-based user input methods.
• Accessibility
  jQuery Mobile is designed with accessibility in mind. It has support for Accessible Rich Internet Applications (WAI-ARIA) to help make web pages accessible for visitors with disabilities using assistive technologies.
• Lightweight and modular
  The framework is lightweight with an overall size (minified and gzipped for Version 1.0.1) of 24KB for the JavaScript library, 7KB for the CSS, plus some icons.
• Theming
  The framework also provides a theme system that allows you to define your own application styling. With the new ThemeRoller application you can easily create your own themes.

The jQuery Mobile framework includes all the UI components needed for building complete mobile web applications and websites: pages, dialogs, toolbars, different kinds of list views, a variety of form elements and buttons, and more. jQuery Mobile is built on top of jQuery core, so you have access to key facilities, including: HTML and XML document object model (DOM) traversing and manipulation; event handling; server communication using Ajax; and animation and image effects for web pages.

With jQuery Mobile, you can write basic mobile web applications without much effort. Because jQuery Mobile is a very comprehensive framework with advanced events and APIs, you can also write advanced mobile web applications and websites.

This article introduces the basics in the latest version of jQuery Mobile (Version 1.0.1). Learn about browser support, the UI components, and the API. To follow along with this article, you will need:

• Previous exposure to HTML
• An understanding of JavaScript fundamentals
• Basic knowledge of jQuery

You can download the jQuery Mobile source code example used with this article. The Resources section has information about jQuery Mobile, jQuery, JavaScript, DOM, HTML5, and more.

Back to top

Browser support

Mobile browsers have come a long way, but not all mobile devices provide support for HTML5, CSS 3, and JavaScript. This arena is where jQuery Mobile's progressive enhancement and graceful degradation support come into play.

jQuery Mobile supports both high-end and less capable devices, such as those without JavaScript support. Progressive enhancement, which is a design philosophy, consists of the following core principles (Wikipedia):

• All basic content should be accessible to all browsers.
• All basic functionality should be accessible to all browsers.
• Enhanced layout is provided by externally linked CSS.
• Enhanced behavior is provided by externally linked JavaScript.
• End user browser preferences are respected.

All basic content should render (as designed) on basic devices, while more advanced platforms and browsers will be progressively enhanced with additional, externally linked JavaScript and CSS.

jQuery Mobile provides support for a large number of mobile devices. jQuery Mobile classifies, or groups, device support into three categories based on their level of support:

• A-grade: Devices with support for a fully enhanced experience with Ajax-based animated page transitions. jQuery Mobile supports over 20 different devices, including: iOS 3.2-5.0; Android 2.1-2.3 and 3.0; BlackBerry 6-7 and Playbook; Skyfire 4.1; Opera Mobile; and the desktop browsers Chrome, Firefox, Internet Explorer, and Opera.
• B-grade: Devices with support for an enhanced experience but without Ajax navigation features. Supported devices include: BlackBerry 5.0, Opera Mini 5.0-6.5, and Nokia Symbian ^3.
• C-grade: Devices with support for a basic, non-enhanced HTML experience. Supported devices include: older smartphones, including BlackBerry 4.x, Windows Mobile, and others.

See Resources for a complete list of jQuery Mobile supported platforms.

The rest of this article discusses the jQuery Mobile page structure, HTML5 data attributes, and UI components.

Back to top

Structure of a jQuery Mobile page

As shown in Listing 1, a typical jQuery Mobile page has three sections: a header, content, and footer section.

lt;div data-role="page" id="page1">
    <div data-role="header">
       <h1>HEADER</h1>
    </div
    <div data-role="content">
       <p>
       CONTENT AREA
       </p>
    </div>
    <div data-role="footer">
       <h1>FOOTER</h1>
    </div>

Figure 1 shows the structure from Listing 1.

The header section is where you would typically place the page headers and things like logos. The content section is where the web application-specific content and the various widgets go. The footer section is great for navigation purposes.

To take advantage of jQuery Mobile advanced features and HTML syntax, a jQuery Mobile HTML document must define the HTML5 doctype. The rest of the HTML document consists of the:

• <head> and <body> sections, where <head> contains the references to jQuery Mobile and the CSS mobile themes
• <body> section that contains the actual jQuery Mobile content

Listing 2 shows an example of an HTML5 jQuery Mobile document.

//Define the HTML5 doctype:

<!DOCTYPE html> 

// Define the HTML5 <head> with references to jQuery, jQuery Mobile and CSS mobile themes:

<html> 

<head> 
    <title>Page Title</title> 
	
    <meta name="viewport" content="width=device-width, initial-scale=1"> 

    <link rel="stylesheet" href="http://code.jquery.com/mobile/1.1.0-rc.1/
jquery.mobile-1.1.0-rc.1.min.css" />
    <script src="http://code.jquery.com/jquery-1.7.1.min.js"></script>
    <script src="http://code.jquery.com/mobile/1.1.0-rc.1/jquery.mobile-1.1.0-rc.1.
min.js"></script>
</head> 

// Define the HTML document <body> that includes the jQuery Mobile elements:

<body> 

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

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

    <div data-role="content">
       <p>
       CONTENT AREA
       </p>

    </div>

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

<div data-role="page" id="page2">
:
:
</div>

</body>
</html>

// The footer can be turned into a navigation bar very easily, as follows:

<center>
<div data-role="footer" class="ui-bar">
<div data-role="controlgroup" data-type="horizontal">
<a href="index.html" data-role="button">One</a>
<a href="index.html" data-role="button">Two</a>
<a href="index.html" data-role="button">Three</a>
<a href="index.html" data-role="button">None</a>
</div>            
</div>
</center>

Figure 2 shows the page footer created in Listing 2.

Though the page, header, content, and footer attributes are optional, it is recommended that you use them; they make the pages clearer to follow with respect to jQuery Mobile.

Single pages, multiple pages, and page linking

A single HTML document can have one or multiple jQuery Mobile pages, as indicated by the data-role="page" attribute. If you have multiple pages, you must specify the id attribute with a unique page ID that is used for linking between internal pages. When loading a multi-page HTML document, only the first page is shown.

jQuery Mobile uses Ajax for page loading, during which it shows the load spinner. If loading is successful, the UI widgets are enhanced, the page is added to the DOM, and page animation or transition is applied.

Linking and loading without Ajax forces the load to use HTTP. You will not get the animated transitions using this approach. Use rel="external", data-ajax="false", or target on the link to load without Ajax.

Back to top

Supported events and methods

In JavaScript, when using jQuery you can refer to the jQuery object itself as $ and gain access to jQuery facilities. The jQuery Mobile framework, which extends jQuery core, is available using $.mobile, which also provides access to the jQuery Mobile-specific events and methods. Some of the events and methods exposed with $.mobile are described below.

Events

As with other jQuery events, you bind to jQuery Mobile events by using the live() and bind() functions. For example, touch events include tap, taphold, and various swipe and virtual mouse events. You can bind to orientation changes and scroll events such as scrollstart and scrollstop. Page events allow you to receive notifications:

• Prior to a page creation
• When a page is created
• Just before the page is shown or hidden
• When the page is shown and hidden

Initializing jQuery Mobile

If you're familiar with jQuery, you might recall that to execute your code as soon as the DOM is loaded you need to initialize inside the $(document).ready() function. With jQuery Mobile, for initialization you bind to the pageinit event, as shown in Listing 3.

$( '#welcomePage' ).live( 'pageinit',function(event){
...
});

The pageinit event is triggered for the referenced page after page initialization occurs. It will work regardless of how the page is loaded (directly or with Ajax).

Overriding jQuery Mobile defaults

If you bind to the mobileinit event, which is triggered when jQuery Mobile starts to execute, you can override some of jQuery Mobile's default values. Listing 4 shows an example. You can override the default page transition, the default page loading text, the default page loading theme, and many others.

$(document).bind("mobileinit", function(){
  //apply overrides here
});

Learn more about jQuery default values by visiting the jQuery Mobile global configuration page (see Resources).

Methods

jQuery Mobile also provides a number of methods with the $.mobile object. Table 1 shows some of the available methods.

The jQuery Mobile methods page has more methods and utilities (see Resources).

Back to top

Widgets and HTML5 data-* attributes

jQuery Mobile relies on HTML5 data-* attributes to support the various UI elements, transitions, and page structure. These HTML5 attributes are the key to jQuery Mobile's simplicity. Browsers that don't support HTML5 will silently discard the HTML5 attributes.

The following list shows the code and renderings of different UI widgets and data-* attributes and how to use them to create UI components.

• Page, header, content, and footer
  
  Listing 5. Page, header, content, and footer
  

  <div data-role="page" id="page1"> <div data-role="header"> <h1>HEADER</h1> </div <div data-role="content"> <p> CONTENT AREA </p> </div> <div data-role="footer"> <h1>FOOTER</h1> </div> </div>

  
  
  
  Figure 3. Page, header, content, and footer
  
  
  
• Basic button
  
  
  Listing 6. Basic button
  

  <a href="index.html" data-role="button" data-icon="info">Button</a>

  
  
  
  
  Figure 4. Basic button
  
  
  
• Checkbox
  
  Listing 7. Checkbox
  

  <input type="checkbox" name="checkbox-1" id="checkbox-0" class="custom" /> <label for="checkbox-0">Checkbox</label>

  
  
  
  Figure 5. Checkbox
  
  
  
• Collapsible
  
  Listing 8. Collapsible
  

  <div data-role="collapsible"> <h3>Header</h3> <p>Paragraph...</p> </div>

  
  
  
  Figure 6. Collapsible
  
  
  
• Open a dialog with transition
  
  Listing 9. Open a dialog
  

  <a href="dialog.html" data-rel="dialog" data-transition="pop">Open dialog</a>

  
  

  The code in Listing 9 is a hyperlink that will open a dialog widget with a transition of type "pop." Figure 7 illustrates an example of a dialog widget.

  
  
  Figure 7. Open a dialog
  
  
  
• Flip toggle switch
  
  Listing 10. Flip toggle switch
  

  <label for="flip-a">Select slider:</label> <select name="slider" id="flip-a" data-role="slider"> <option value="off">Off</option> <option value="on">On</option> </select>

  
  
  
  Figure 8. Flip toggle switch
  
  
  
• List view
  
  Listing 11. List view
  

  <ul data-role="listview" data-theme="g"> <li><a href="Friends.html">Friends</a></li> <li><a href="SendMessage.html">Send Message</a></li> <li><a href="Share.html">Share</a></li> </ul>

  
  
  
  Figure 9. List view
  
  
  
• Nav bar
  
  Listing 12. Nav bar
  

  <div data-role="navbar"> <ul> <li><a href="a.html" class="ui-btn-active">One</a></li> <li><a href="b.html">Two</a></li> </ul> </div>

  
  
  
  Figure 10. Nav bar
  
  
  
• Radio button
  
  Listing 13. Radio button
  

  <fieldset data-role="controlgroup"> <legend>Choose a pet:</legend> <input type="radio" name="radio-choice-1" id="radio-choice-1" value="choice-1" checked="checked" /> <label for="radio-choice-1">Cat</label> <input type="radio" name="radio-choice-1" id="radio-choice-2" value="choice-2" /> <label for="radio-choice-2">Dog</label> <input type="radio" name="radio-choice-1" id="radio-choice-3" value="choice-3" /> <label for="radio-choice-3">Hamster</label> </fieldset>

  
  
  
  Figure 11. Radio button
  
  
  
• Select (form)
  
  Listing 14. Select (form)
  

  <label for="select-choice-0" class="select">Shipping method:</label> <select name="select-choice-0" id="select-choice-1"> <option value="standard">Standard: 7 day</option> <option value="rush">Rush: 3 days</option> <option value="express">Express: next day</option> <option value="overnight">Overnight</option> </select>

  
  
  
  Figure 12. Select (form)
  
  
  
• Slider
  
  Listing 15. Slider
  

  <label for="slider-0">Input slider:</label> <input type="range" name="slider" id="slider-0" value="60" min="0" max="100" />

  
  
  
  Figure 13. Slider
  
  
  
• Text input
  
  Listing 16. Text input
  

  <label for="basic">Text Input:</label> <input type="text" name="name" id="basic" value="" />

  
  
  
  Figure 14. Text input
  
  
  
• Text area
  
  Listing 17. Text area
  

  <label for="textarea-a">Textarea:</label> <textarea name="textarea" id="textarea-a"> Basic textarea. </textarea>

  
  
  
  Figure 15. Text area
  
  
  
• Grid
  
  Listing 18. Grid
  

  <div class="ui-block-a">Block A</div> <div class="ui-block-b">Block B</div> <div class="ui-block-c">Block C</div> </div>

  
  

  Note:

  • For two-column use the ui-grid-a class
  • For three-column use the ui-grid-b class
  • For four-column use the ui-grid-c class
  • For five-column use the ui-grid-d class
  
  
  Figure 16. Grid
  
  
  

The data-role attribute is used to define the different widgets. Not all of the UI widgets are driven by the data-role attribute, though (select, slider, and text input, for example). See the data- attribute reference for more detailed information about the different data-* attributes (see Resources).

As mentioned, the jQuery Mobile UI framework includes all the UI components needed for building complete mobile web applications and websites including pages, dialogs, toolbars, different kinds of list views, a variety of form elements, buttons, and others. We've covered the HTML5 data-* attributes used to define the different jQuery Mobile UI widgets. The rest of this section discusses the most common jQuery Mobile UI widgets.

Dialogs

Modal dialogs are an essential type of page that can be very useful for alerts or messages to the user. Any page can be turned into a modal dialog by adding the data-rel="dialog" attribute to the page's anchor link, as follows.

<a href="tc.html" data-rel="dialog" data-transition="pop">Terms of 
Use</a>

You can apply transitions and themes to the dialogs. The jQuery Mobile Dialog page has more information for reference (see Resources).

List views

List views are one of the most important UI elements for mobile applications. jQuery Mobile provides support for a rich set of list view elements, including basic, nested, split button, numbered, numbered bubble, and icon lists. Let's take a look at the code and renderings of some list views.

• Basic-linked list
  
  Listing 19. Basic-linked list
  

  <ul data-role="listview"> <li><a href="index.html">Acura</a></li> </ul>

  
  
  
  Figure 17. Basic-linked list
  
  
  
• Nested list
  
  Listing 20. Nested list
  

  <ul data-role="listview"> <li> <h3>Animals</h3> <p>All your favorites from aarkvarks to zebras.</p> <ul> <li>Pets <ul> <li><a href="index.html">Canary</a></li> <li><a href="index.html">Cat</a></li> <li><a href="index.html">Dog</a></li> <li><a href="index.html">Gerbil</a></li> <li><a href="index.html">Iguana</a></li> <li><a href="index.html">Mouse</a></li> </ul> </li> </ul> </ul>

  
  
  
  Figure 18. Nested list
  
  
  
• Numbered list
  
  Listing 21. Numbered list
  

  <ol data-role="listview"> <li><a href="index.html">The Godfather</a></li> </ol>

  
  
  
  Figure 19. Numbered list
  
  
  
• Split button list
  
  Listing 22. Split button list
  

  <ul data-role="listview" data-split-icon="gear" data-split-theme="d"> <li> <a href="index.html"> <img src="images/album-ws.jpg" /> <h3>Elephant</h3> <p>The White Stripes</p> </a><a href="lists-split-purchase.html" data-rel="dialog" data-transition="slideup">Purchase album</a> </li> </ul>

  
  
  
  Figure 20. Split button list
  
  
  

Inset-style lists

jQuery Mobile supports all of its list views as inset-style lists (lists with rounded corners) by specifying the data-insert attribute, as shown in Figure 21.

Listing 23 shows the code an inset-style list.

<ul data-role="listview" data-inset="true">
    <li>
      <a href="index.html">Get Friends</a>
    </li>
    <li>
      <a href="index.html">Post to Wall</a>
    </li>
    <li>
      <a href="index.html">Send Message</a>
    </li>
</ul>

jQuery Mobile provides a rich set of list views. For more information, see the jQuery Mobile list view page (see Resources).

Forms

Forms are a common web artifact for posting information to a server. jQuery Mobile supports many form UI components: text inputs, search inputs, slider, flip toggle switch, radio buttons, check boxes, select menus, and theming forms. They can all be created easily. The previous section covered the majority of these elements.

jQuery Mobile provides a rich set of form elements. Listing 24 shows a form with a select menu and a submit button.

<form action="forms-results.php" method="get"> 
    <fieldset> 
        <div data-role="fieldcontain">
            <label for="select-options" class="select">Choose 
an option:</label>
            <select name="select-options" id="select-options">
                <option value="option1">Option 1</option>
                <option value="option2">Option 2</option>
                <option value="option2">Option 3</option>
            </select>
        </div>
        <button type="submit">Submit</button> 
    </fieldset> 
</form>

Select menus are driven by native <select name="select-options" id="select-options">, but jQuery Mobile improves on its "look and feel." The <div data-role="fieldcontain"> statement groups the different values for visualization purposes. The form itself is defined by native <form action="..." method="get">.

Figure 22 shows the result from Listing 24.

The jQuery Mobile form elements page has more information (see Resources).

Back to top

Page transitions

jQuery Mobile supports a number of cool CSS-based transitions, listed in Table 2, that can be applied to both dialogs and pages.

To force a specific animation, add the data-transition attribute on the link, as shown in Listing 25.

<a href="../nav.html" data-icon="search" data-iconpos="notext" data-rel="dialog"
 data-transition="fade">Search</a>

Transitions are hardware accelerated and require 3D transform support by the browser. Devices that don't provide 3D support will fall back to fade.

The jQuery Mobile transitions page shows the transitions in action and other related information (see Resources).

Back to top

Themes and ThemeRoller

With jQuery Mobile, you can use the data-theme attribute to customize the look of your application with themes. jQuery Mobile provides one default theme and five additional swatches, named A through E, as shown in Table 3.

Theme	Style
Default theme
Swatch A
Swatch B
Swatch C
Swatch D
Swatch E

You can theme individual elements, such as a page, a button, and so on.

With the ThemeRoller web-based application, shown in Figure 23, you can create themes for your mobile web application or mini website. You can also use ThemeRoller to build your own theme, download the custom CSS file, and use it on your project.

Back to top

Conclusion

In this article, you have learned some of the basics of the jQuery Mobile framework. Examples in this article showed how to use basic pages, navigation, toolbars, list views, form controls, and transition effect. The framework offers much more, including other methods and events for advanced applications. With jQuery Mobile you can also use and customize widgets. Hopefully you're now inspired to write functional mobile web application UIs using jQuery Mobile.

Back to top

Download

Information about download methods

Resources

Learn

• jQuery Mobile framework: Learn about the platforms, themes, resources, documentation, news, and more.
  
  
• Documentation: Access all of the jQuery documentation.
  
  
• ThemeRoller for jQuery Mobile: See how to create up to 26 theme "swatches" lettered A-Z, each with a unique color scheme, then mix and match for unlimited possibilities.
  
  
• Learn more about jQuery Mobile:
  • Supported platforms
  • data- attribute
  • Form elements
  • Transitions
  • Methods
  
  
• Demos and documentation: Get an overview, learn about the API and components, and access demo code.
  
  
• Mobile Graded Browser Support: View a supported browser matrix for jQuery Mobile.
  
  
• JavaScript Guide: Explains everything you need to know about using JavaScript.
  
  
• Mozilla Developer Center: A great resource for web developers.
  
  
• "jQuery Fundamentals" (Rebecca Murphey, 2010): Provides a comprehensive overview of the jQuery JavaScript library.
  
  
• jQuery: Plugins/Authoring: Shows how to write your own jQuery plugins.
  
  
• "What is the Document Object Model?" (W3C, November 2000): Learn more about the Document Object Model?.
  
  
• DOM objects and methods: A JavaScript tutorial that provides a comprehensive listing of all properties, collections, and methods of the W3C DOM.
  
  
• WAI-ARIA overview: The Accessible Rich Internet Applications Suite, which defines a way to make web content and web applications more accessible to people with disabilities.
  
  
• Progressive enhancement (Wikipedia): Read about this strategy for web design that emphasizes accessibility, semantic HTML markup, and external stylesheet and scripting technologies.
  
  
• "JavaScript and the Document Object Model" (developerWorks, July 2002): Explore the JavaScript approach to DOM and chronicles the building of a web page to which the user can add notes and edit note content.
  
  
• "Understanding DOM" (developerWorks, March 2007): This tutorial teaches you about the structure of a DOM document.
  
  
• Read the HTML5 Specification from the W3C.
  
  
• developerWorks Web development zone: Find articles covering various web-based solutions. See the Web development technical library for a wide range of technical articles and tips, tutorials, standards, and IBM Redbooks.
  
  
• developerWorks Mobile development zone: Find how-to articles, evaluation code, and technical perspectives on a range of topics for mobile developers.
  
  
• developerWorks technical events and webcasts: Stay current with technology in these sessions.
  
  
• developerWorks Live! briefings: Get up to speed quickly on IBM products and tools as well as IT industry trends.
  
  
• developerWorks on-demand demos: Watch demos ranging from product installation and setup for beginners, to advanced functionality for experienced developers.
  
  
• developerWorks on Twitter: Join today to follow developerWorks tweets.
  
  

Get products and technologies

• jQuery Mobile: Download 1.1.0. The jQuery Mobile Alpha 2 is also available.
  
  
• PhoneGap is an open source development framework for building cross-platform mobile apps.
  
  
• IBM product evaluation versions: Download or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2, Lotus, Rational, Tivoli, and WebSphere.
  
  

Discuss

• jQuery Mobile Forum: Get answers to your jQuery Mobile questions.
  
  
• developerWorks community: Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.
  
  
• Find other developerWorks members interested in web development.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Browser support
• Structure of a jQuery Mobile page
• Supported events and methods
• Widgets and HTML5 data-* attributes
• Page transitions
• Themes and ThemeRoller
• Conclusion
• Download
• Resources
• About the author
• Comments

Dig deeper into Web development on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers