Introduction
Welcome to jQuery Mobile. If you've never worked with jQuery before, don't worry. While an understanding of jQuery (and JavaScript in general) is certainly a good idea, you don't need to bring any skills to the table outside of basic HTML markup. In a few short minutes this guide will walk you through the basics of a simple jQuery Mobile-based web site and help guide you to where you can learn more. Before starting make sure you have a basic text editor of some sort. The editor that ships with your operating system is fine.
Quick Note on Versioning
At the time of publication, this guide was written for jQuery Mobile 1.0 Alpha 4.1. Code samples will reference those libraries. The guide will be updated as soon as possible after the final release to reflect the latest code base. Users should be able to cut and paste all code samples from this guide and run them as is.
Getting Started
Before you begin, you may, if you wish, download the source code for jQuery Mobile. The latest, stable bits may be found here: http://jquerymobile.com/download/. Our code however will be making use of jQuery's CDN (content delivery network).
Every jQuery Mobile project begins with at least one HTML file. Open a new file in your favorite editor and name it index1.html. Our first page will begin with an HTML 5 doctype.
<!DOCTYPE html>
This will be required for any page used with the framework so don't forget it! (For folks who want a bit more explanation, it will help us work with the data attributes we will be introducing in a minute.) Now let's look at the head out of document. There are three critical parts to the code block below. Every jQuery Mobile application will need:
- the CSS file
- the core jQuery library
- and the jQuery Mobile library
<html>
<head>
<title>Page Title</title>
<link rel="stylesheet" href="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.css" />
<script src="http://code.jquery.com/jquery-1.5.2.min.js"></script>
<script src="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.js"></script>
</head>
Now let's look at the body of our HTML page. jQuery Mobile takes ordinary HTML tags and enhances them to render well on mobile devices. In order for this to work your HTML needs to make use of data attributes. These are attributes that will look like this:
<div id="someId" data-something="foobar">
See the data-something tag? We can use any combination of data- plus a label and a value and the browser will simply ignore it. While the browser ignores it, however, jQuery Mobile can use these attributes as markers to help it render the page. jQuery Mobile looks for a div tag with a particular data-role value: page. Here is a simple example:
<div data-role="page">
This is my page.
</div>
The data-role attribute here tells jQuery Mobile to treat the content within it as one page of your application. Given what we know so far, let's look at a complete, but simple, jQuery Mobile page:
index1.html
<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
<meta name="viewport" content="width=device-width, minimum-scale=1, maximum-scale=1">
<link rel="stylesheet" href="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.css" />
<script src="http://code.jquery.com/jquery-1.5.2.min.js"></script>
<script src="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.js"></script>
</head>
<body>
<div data-role="page">
<p>Oh snap, I'm a mobile developer.</p>
</div>
</body>
</html>
You'll notice right away that I've not written any JavaScript. I've simply made use of HTML and included the relevant jQuery Mobile resources. Here is how it renders in the browser:
Ok, so not really that impressive. But let's see what happens when we add a few more elements to our HTML page. Within the context of our "page" we can also add 3 optional sections: a header, the body content, and a footer. As before, these are done with data attributes. Here is the next version of our page:
index2.html
<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
<link rel="stylesheet" href="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.css" />
<script src="http://code.jquery.com/jquery-1.5.2.min.js"></script>
<script src="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.js"></script>
</head>
<body>
<div data-role="page">
<div data-role="header">
<h1>My Header</h1>
</div>
<div data-role="content">
<p>Oh snap, I'm a mobile developer.</p>
</div>
<div data-role="footer">
<h4>My Footer</h4>
</div>
</div>
</body>
</html>
I've replaced the simple paragraph of text with three new div blocks. My first div has a data-role value of header. My second has a role of content. And my third one has a footer role. Again - no JavaScript. But look at how this version renders:
As you can see, there is a pretty radical difference in how this version renders in the mobile browser. Both my header and footer were automatically styled to look - well more like a header and footer.
Adding Pages
If our web site was a grand total of one page, our job would be done, but unfortunately, most sites consist of multiple pages. jQuery Mobile provides two interesting ways to add additional pages to your site. First let's look at how your can add additional pages within the same HTML page.
index3.html
<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
<link rel="stylesheet" href="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.css" />
<script src="http://code.jquery.com/jquery-1.5.2.min.js"></script>
<script src="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.js"></script>
</head>
<body>
<div data-role="page" id="main">
<div data-role="header">
<h1>My Header</h1>
</div>
<div data-role="content">
<p>Oh snap, I'm a mobile developer.</p>
<p>
Here is a <a href="#page2">link</a> to another page.
</p>
</div>
<div data-role="footer">
<h4>My Footer</h4>
</div>
</div>
<div data-role="page" id="page2">
<div data-role="header">
<h1>Page Two</h1>
</div>
<div data-role="content">
<p>
Welcome to page 2. Enjoy your stay.
</p>
</div>
<div data-role="footer">
<h4>My Footer</h4>
</div>
</div>
</body>
</html>
Let's focus in on what changed. You'll notice I now have two div blocks with the data role of page. The first one is much like our last version. I've added an id, "main", to identify it as a unique page to jQuery Mobile. Inside my page, notice I added a second paragraph with a simple link. I'm using #page2 as my URL. This tells jQuery Mobile that the page should exist within the same document. And as you can see, it does, right below the first page. I've given it an ID that matches my link (page2) and provided another header, content, and footer area. When viewed in the web browser, the second page is completely hidden:
Clicking on the link creates an automatic transition (that you can configure if you want) to the second page:
Notice too that a back button is automatically created. (And yes - you can configured that too.) Without writing a line of JavaScript you've got a mobile friendly site now that will let you switch from page to page seamlessly and provide automatic navigation helpers. That's hot. But you probably don't want to write one HTML page with multiple pages in it. It would quickly become unmanageable to deal with lots of pages within one HTML file. You will typically link to other pages. Simple links to other pages will work the same as you saw above. jQuery Mobile will use Ajax to load the page and generate a nice transition. Let's modify our previous example to add a new link.
index4.html
<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
<link rel="stylesheet" href="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.css" />
<script src="http://code.jquery.com/jquery-1.5.2.min.js"></script>
<script src="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.js"></script>
</head>
<body>
<div data-role="page" id="main">
<div data-role="header">
<h1>My Header</h1>
</div>
<div data-role="content">
<p>Oh snap, I'm a mobile developer.</p>
<p>
Here is a <a href="#page2">link</a> to another page.
</p>
<p>
Here is a <a href="newpage.html">link</a> to a new page.
</p>
</div>
<div data-role="footer">
<h4>My Footer</h4>
</div>
</div>
<div data-role="page" id="page2">
<div data-role="header">
<h1>Page Two</h1>
</div>
<div data-role="content">
<p>
Welcome to page 2. Enjoy your stay.
</p>
</div>
<div data-role="footer">
<h4>My Footer</h4>
</div>
</div>
</body>
</html>
Our template now has two links. We've kept the first link to page 2. But beneath it we added a link to newpage.html. Notice that this is just a simple link, like before, but jQuery Mobile is going to automatically handle it. Now let's look at newpage.html.
newpage.html
<div data-role="page">
<div data-role="header">
<h1>The new Page</h1>
</div>
<div data-role="content">
<p>This is my new page!</p>
</div>
<div data-role="footer">
<h4>Page Footer</h4>
</div>
</div>
As you can see, creating a page in jQuery Mobile follows a standard format. One div with the proper data-role and then content within in it. The only difference between this page and the last one is that it is used in a new file. You can run the new template now and browse to both pages. jQuery Mobile treats them the same. Note that any links to external domains will not be loaded via Ajax. You can also disable loading by Ajax on a link by link basis.
UI Widgets
So far we've focused on pages and basic navigation.jQuery Mobile also has a large set of UI widgets that work much in the same way. You take simple HTML, add a data-role to it, and jQuery Mobile will automatically enhance it to look nicer and work better in a mobile environment. This quick start won't discuss all of them, but will demonstrate one example - lists. Lists are an easy way to provide menu type navigation to end users. jQuery Mobile makes it trivial then to enhance a simple HTML list. Let's look at an example.
index5.html
<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
<link rel="stylesheet" href="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.css" />
<script src="http://code.jquery.com/jquery-1.5.2.min.js"></script>
<script src="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.js"></script>
</head>
<body>
<div data-role="page" id="main">
<div data-role="header">
<h1>My Header</h1>
</div>
<div data-role="content">
<ul data-role="listview">
<li><a href="#page2#">Page Two</a></li>
<li><a href="newpage.html">New Page</a></li>
</ul>
</div>
<div data-role="footer">
<h4>My Footer</h4>
</div>
</div>
<div data-role="page" id="page2">
<div data-role="header">
<h1>Page Two</h1>
</div>
<div data-role="content">
<p>
Welcome to page 2. Enjoy your stay.
</p>
</div>
<div data-role="footer">
<h4>My Footer</h4>
</div>
</div>
</body>
</html>
Our page content has been replaced by a UL tag. Notice though the addition of a data-role attribute. By telling jQuery Mobile that the HTML represents a list view, the look and feel of the list will be completely enhanced:
Notice the items now take up the complete width of the page. Also note the addition of arrows on the right. All of this was done with the addition of the data-role. Let's look at one more modification.
index6.html
<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
<link rel="stylesheet" href="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.css" />
<script src="http://code.jquery.com/jquery-1.5.2.min.js"></script>
<script src="http://code.jquery.com/mobile/1.0a4/jquery.mobile-1.0a4.min.js"></script>
</head>
<body>
<div data-role="page" id="main">
<div data-role="header">
<h1>My Header</h1>
</div>
<div data-role="content">
<ul data-role="listview" data-inset="true">
<li><a href="#page2#">Page Two</a></li>
<li><a href="newpage.html">New Page</a></li>
</ul>
</div>
<div data-role="footer">
<h4>My Footer</h4>
</div>
</div>
<div data-role="page" id="page2">
<div data-role="header">
<h1>Page Two</h1>
</div>
<div data-role="content">
<p>
Welcome to page 2. Enjoy your stay.
</p>
</div>
<div data-role="footer">
<h4>My Footer</h4>
</div>
</div>
</body>
</html>
So what changed here? Just the inclusion of data-inset="true". Let's now look at what jQuery Mobile does with it:
See the nice rounded corners and the padding? This is just one example of many forms of list views contained within jQuery Mobile.
Where to Go Next?
This guide has just covered the basics of jQuery Mobile development. To continue your journey, read over the docs (http://jquerymobile.com/demos/1.0a4.1/) and start playing!