The newest member of the jQuery family of projects is jQuery Mobile. A good way to describe what jQuery Mobile is to think of it as jQuery UI for mobile devices. If you have wanted to write mobile-optimized UIs over your applications, jQuery Mobile is a library that you will want to add to your bag of tricks. Like jQuery UI, jQuery Mobile is themeable. This article makes two assumptions. First, you are familiar with jQuery and second, you are familiar with jQuery UI. If you are not familiar with jQuery or jQuery UI, I suggest that you take a moment to familiarize yourself with those libraries. Fortunately, the websites for these projects (jquery.com and jQueryUI.com respectively) are replete with comprehensive documentation and code examples. jQuery Mobile is no different. The official website for jQuery Mobile is jquerymobile.com. As of this writing, jQuery Mobile 1.0 Beta 3 has been released. Its beta status notwithstanding, jQuery Mobile is ready for primetime and has been incorporated into many applications already. In this article, I will cover what you need to get started with some simple examples that illustrate how to create one page and multi-page apps. In addition, I’ll touch upon the theming capabilities in jQuery Mobile.

A good way to think of jQuery Mobile is that it is jQuery UI for mobile devices.

What You Need to Get Started

You need three files to get started with jQuery Mobile (the X in the name is a placeholder for the version):

In addition to these three files, you will also need the supporting image files. You can download these resources from the jQuery Mobile site: jquerymobile.com/download. The zip file contains both minified and unminified js files. The following code snippet shows how to bootstrap jQuery Mobile:

<!--CSS-->
<link rel="stylesheet" href="jquery.mobile
  -1.0b3.min.css"/>
<!--jQuery Core Library -->
<script type="text/javascript" src="jquery-
  1.6.4.min.js"></script>
<!--jQuery Mobile Library -->
<script type="text/javascript" src="jquery.mobile-
  1.0b3.min.js"></script>

Like all things jQuery related, everything starts with the core jQuery library, in this case, jquery-1.6.4.min.js. Like jQuery UI, jQuery Mobile extends the core library. The third file is the required CSS to format and theme the pages. This is exactly how jQuery UI works. Once you have the necessary js libraries and CSS in your project, you are ready to get up and running with jQuery Mobile.

The Basic Page Template

Let’s start with the simplest thing possible to get a page up and running. The following code, illustrated in Figure 1, shows the basic template that all jQuery Mobile pages would follow:

Figure 1: The code in Listing 1 rendered on an iPhone.

I need to point out two things in this example. First, you can see the viewport metatag working. The page has been formatted to fit within the iPhone display. Second, take a moment to review the code in Listing 1. Take note of the data-role attribute. This is what jQuery Mobile uses to identify the page components. The outer div is a page, which has a header, content and footer.

Working with Multiple Pages, Transitions and Themes

In the real world, our applications consist of more than just one page. This is where jQuery really shines because jQuery makes it easy to manage multiple pages and the transitions between those pages. For example, from page 1 to 2, you may want page 2 to fade in. Or, you may want page 2 to slide from the bottom, top or side. Or, you may want page 2 to flip as it displays in place of page 1.

In order to see how these various transitions work, you can visit this demo page: http://jquerymobile.com/demos/1.0b3/docs/pages/page-transitions.html. Ideally, you will want to visit this page with a mobile device so that you can see exactly how jQuery Mobile optimized pages will appear. If you visit the site on your non-mobile device, make sure you use a webkit browser such as Chrome or Safari. With these browsers, you will get a sense of how the various page transitions will appear on a mobile device. Thanks to Irwin Hurst of CEI’s Microsoft Practice for pointing out this fact when I circulated a draft of this article for peer review. Listing 2 illustrates an html fragment of the code required to handle multiple pages. Note: For the sake of brevity, I have omitted the html and head tags.

In many ways, the multi-page example works like the tabs and accordion widgets in jQuery UI. In both cases, there are nested divs, some of which have their display style set to “none.” It’s not something you have to do explicitly. Rather, jQuery Mobile handles that for you. Notice the anchor tags on each page. Each references the other page. Also note the data-transition attribute. This is how you control the way the linked page is displayed. In this example, from page 1, page 2 will flip. Page 1 flips and it appears like flipping a piece of paper over. In this case, page 2 is on the other side. From page 2, page 1 fades in and replaces page 2 in the display. It’s a very simple feat to accomplish and best of all, jQuery Mobile does the heavy lifting for you! Another element to note for the links is the data-role attribute. The links in this example will be displayed as buttons. Figure 2 illustrates how page 1 will appear on an iPhone.

Figure 2: The data-role attribute determines how a given element will be displayed.

You can also display a page as a dialog. Revising the example slightly, the second page has been refactored into its own html file. The following is the revised link to page 2 in the first page:

<p><a href="page2.html" data-role="button"
data-rel="dialog">View Page 2</a></p>

The data-rel attribute specifies that the link target is to be displayed as a dialog. The code for page 2 is nearly identical to what is listed in Listing 2. I did make one change to the page div: 

<div data-role="page" id="page2" data-theme="e">

The data-theme attribute controls which theme, or as jQuery Mobile refers to them as swatches, is applied to the page. I also removed the button to navigate back to page 1 because dialogs are modal. jQuery Mobile adds a close button to the header for us. When that button is clicked, the display reverts back to the page that called the dialog. Figure 3 illustrates how page 2 appears.

Figure 3: This dialog illustrates the Swatch E theme.

Other jQuery UI Display Elements and Events

When you create mobile UIs, remember that you have limited screen real estate. In some cases, you may wish to initially hide some content and only display it when the user wishes to see the content. The following code snippet re-works the page 1 example above by surrounding the content with a div tag that has the data-role = “collapsible”. Figure 4 illustrates how the page will first appear and Figure 5 illustrates how the page appears with the expanded content.

Figure 4: Page 1 with collapsed collapsible content.
Figure 5: Page 1 with expanded collapsible content.
<div data-role="collapsible">
 <h3>The content below is hidden</h3>
 <div data-role="content">
 <p>This is the first page.</p>
 <p><a href="page2.html" data-role="button" data-
   rel="dialog">View Page 2</a></p>
 </div>
</div>

Looking at Figure 5, you will note that the header text changed. The change did not happen automatically. Given the formerly hidden content is now displayed; the original text that indicated the content is still hidden would not make sense. Like everything else in jQuery, you’ll find exposed events to which you can attach handlers. In this case, the two events you are interested in are the expand and collapse events. The following script attaches handlers to the expand and collapse events:

<script type = "text/javascript">
 $("#hiddencontent").live('expand',
  function (domelement) {
   toggleText(domelement, "expand");
  });
    
 $("#hiddencontent").live('collapse',
  function (domelement) {
   toggleText(domelement, "collapse");
 });
    
 function toggleText(domElement, event) {
 var heading = $(domElement.target).find("h3");
 var newText = (event == "collapse" ? "displayed" :
  "hidden");
 var oldText = (newText == "hidden" ? "displayed" :
 "hidden");
 var newHtml = heading.html().replace(newText,
  oldText);
 heading.html(newHtml);
 }
</script>

Note that the handlers call the same toggleText function. The difference is the parameter passed, which indicates which event called the function. This is JavaScript, and the SOLID principles and the over-arching DRY (Don’t Repeat Yourself) rules apply!

Another jQuery Mobile UI element that you will likely use often is the list view. Figure 6 illustrates a list view example as rendered on an iPad.

Figure 6: An example of a jQuery Mobile list view

The following html fragment inside the body tag is all that is required to create a list view:

<div data-role="page" id="page1">
 <div data-role="header">
  <h1>List View Example</h1>
 </div>
    
<ul data-role="listview" data-theme="g">
 <li><a
href="http://www.microsoft.com/download/en/details.aspx
 ?id=5388">ASP.NET MVC 1</a></li>
 <li><a href="http://msdn.microsoft.com/en-
  us/library/dd394709.aspx">ASP.NET MVC 2</a></li>
 <li><a href="http://msdn.microsoft.com/en
  -us/library/gg416514(v=vs.98).aspx">ASP.NET MVC
   3</a></li>
<li><a href="http://www.asp.net/learn/whitepapers/mvc4-
  release-notes">ASP.NET MVC 4 Preview</a></li>
 </ul>
    
<div data-role="footer">
  <h4>ASP.NET MVC Documentation Links</h4>
</div>
</div>

In the previous examples, the same header and footer elements are used. To create a list view, you simply create an unordered list. List views can get quite complex. They can be nested, host thumbnail images, icons, etc. Notice the data-role attribute for the ul tag. Its value is “listview.” By now, you should notice a repeatable pattern wherein the data-role attribute is what drives the appearance of your jQuery Mobile powered UIs.

Conclusion

What has been presented thus far, while a good start, only scratches the surface of what you can accomplish with jQuery Mobile. Like jQuery UI, you can use a variety of UI widgets. For example, there are sliders, toolbars, more complex list views, layout grids, accordion and more complex collapsible displays to name a few. My goal in this article was to introduce you to what jQuery Mobile can do and why you should consider using it today. In addition to the UI elements, there is a rich event model that your js/jQuery code can take advantage of and that was illustrated in the collapsible element example in Figures 4 and 5, respectively. There are plenty of additional practical examples on the jQuery Mobile site that will help you get up and running quickly with jQuery Mobile.