Working with Pages in jQuery Mobile. With most of the heavy lifting being done by the framework it’s easy to focus on the results of the website being built. In this excerpt from jQuery Mobile Develop and Design, Kris Hadlock explains the internal functionality behind how pages work in jQuery Mobile so you can get ready to write your own custom functionality.
This excerpt is from the Rough Cuts version of the jQuery Mobile Develop and Design book and may not represent the final version of this material.
Now that we’ve covered the basics of structuring mobile web pages we will take a deeper look and get a better understanding of the functionality behind them. As mentioned in Chapter 3, there are two ways to structure webpages for jQuery Mobile. The two different options are to 1. incorporate all the pages within the same file or 2. create separate files for each page like a typical website. Let’s start by taking a look at the multi-page template.
Multi-page Template
Internal linking occurs automatically when you have multiple jQuery Mobile pages within the same HTML file. As we’ve covered, jQuery Mobile pages are defined by adding a data-role with a value of page to an HTML element and anything within that “page” becomes relative to that page. In jQuery Mobile typical separate webpages are considered Single page templates, while webpages that contain multiple “pages” are considered Multi-page templates. Let’s refer back to our multi-page template example from the previous chapter (with a few small additions).
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Multi-page template - jQuery Mobile: Design and Develop</title>
<link rel="stylesheet" href="https://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.css" />
<script src="https://code.jquery.com/jquery-1.6.4.min.js"></script>
<script src="https://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.js"></script>
<script type="text/javascript" src="assets/js/ui.js"></script>
</head>
<body class="container">
<div data-role="page" id="page-one" data-title="Page 1">
<div data-role="header">
<h1>Page 1</h1>
</div>
<div data-role="content">
<p>Body copy for page 1</p>
<p><a href="#page-two">Link to page 2</a></p>
</div>
<div data-role="footer">
Copyright
</div>
</div>
<div data-role="page" id="page-two" data-title="Page 2">
<div data-role="header">
<h1>Page 2</h1>
</div>
<div data-role="content">
Body copy for page 2
<a href="#page-one">Link to page 1</a>
</div>
<div data-role="footer">
Copyright
</div>
</div>
</body>
</html>
As you can see within this multi-page template there are two “pages” defined by div elements with custom ids. The jQuery Mobile framework will only show one of these pages at a time, plus it will use the data-title attribute to change the page title dynamically. The page that is shown by default is determined based on the order of the source code. In this example, the first page has an id of page-one, but if the pages in this file were switched, so that the element with an id of page-two were first, then that would be the default page to load. In other words, the value of the id attribute doesn’t determine what page is shown by default, the default page is only determined by the source code order. However, the id is used for other important purposes.
This is where jQuery Mobile pages begin to act like separate web pages. As you can see hyperlinks have been added to the original template in order to link from one page to another. This is sort of like toggle functionality that is common to see in JavaScript development, where id values are used to hide and reveal certain HTML elements. The difference in this case is that jQuery Mobile handles the functionality for you. To link from one page to another you simply need to:
- Create a hyperlink
- Type the pound (#) sign
- Specify the id value of the “page” that you want to link to
<a href="#page-two">Link to page 2</a>
It’s similar to creating a page anchor, the difference is that you’re referencing the id value of another page. It’s important to remember that each “page” needs to have a unique id value, in this case I’ve used page-one and page-two, but you can use something more descriptive and relative to the content that is contained within your jQuery Mobile page. The cool thing about the jQuery Mobile framework is that it will dynamically transition from one “page” to another without making you write an ounce of code.
Single-page Template
Single-page templates are separate HTML files that act as independent webpages, just like any standard webpage. The main difference is in how jQuery Mobile connects webpages using Ajax. As with multi-page templates, the Ajax-based navigation in single-page templates uses hash tags to create a page history. The Ajax-based navigation used by jQuery Mobile is default, but it can be turned off with by setting the ajaxEnabled setting to false in the configuration. We will learn more about the configuration settings later in the book.
AJAH
AJAH is an abbreviation that is sometimes used for Asynchronous JavaScript and HTML. AJAH is essentially Ajax without the XML, the XMLHttpRequest is still used, but HTML is being exchanged with the server rather than XML. This is what jQuery Mobile uses as the user browses independent webpages. We briefly covered how the jQuery Mobile framework uses the XMLHttpRequest to load subsequent pages in chapter 3, but there is a lot to learn and understand about this simple request.
One of the great things about the jQuery Mobile framework is how the history is tracked. jQuery Mobile supports the back and forward buttons! Also, while subsequent pages are loading the framework provides a default loading message and transitions between pages. The default page transition is to fade between two pages and the default loading message is a spinning icon with a “loading…” message. Both of these options are configurable, as we will learn in the next chapter. For now, let’s see how hashes and history work in jQuery Mobile.
Hashes and History
jQuery Mobile uses the hash tag to manage history in single- and multi-page templates. The window objects location.hash is used to make changes and updates to the history, so that the back and forward buttons function as usual, which is uncommon with other Ajax-based systems. Essentially, jQuery Mobile prevents the default functionality of all hyperlinks and uses the hash tag functionality to handle history. Not only is the history updated, the hash system also creates a valid URL that can be bookmarked for later reference.
The only issue with the hash-based navigation that jQuery Mobile provides is that it doesn’t support deep linking. However, there are some workarounds that you can use to provide support for this functionality. With a little help from jQuery you can add a script like the following to your web page and your deep links will function as usual.
$(document).ready(function() {
$('a[href^=#]').bind('click vclick', function (e) {
location.hash = $(this).attr('href');
return false;
});
});
In HTML all hyperlinks that include a pound sign as their first character are identified as anchors. This script uses a regular expression that includes the carat symbol to identify all anchor elements that have an href attribute with a value that begins with the pound sign. Once these elements have been selected we use the bind method to bind a click and vclick event to the anchor tags and assign an anonymous function handler as the callback. The callback function sets the window objects location.hash to the value of the anchor and uses return false to prevent the browser from performing the default action associated with clicking the hyperlink.
Link Types
jQuery Mobile supports standard HTML link types as well as a number of custom link types that are related to the mobile experience. Tables 4.1-4.3 offer a list of the supported link types available through the jQuery Mobile framework. Each table shows options categorized based on their end result and/or support of Ajax.
Table 4.1 (Link Types that Support Ajax)
Supporting Ajax
| Hyperlink Markup | Description |
| <a href=”https://www.jquerymobile.tv”>Hyperlink within same domain</a> | A standard HTML link that is transformed by the jQuery Mobile framework to use Ajax, include page transitions and support page history. |
| <a href=”https://www.jquerymobile.tv” data-rel=”dialog”>Open a dialog</a> | Used for dialog windows. This option is not tracked in page history. |
| <a href=”https://www.jquerymobile.tv” data-rel=”back”>Back button</a> | This option can be used to navigate back in page history. A great option for providing a back button from a page or dialog. The href is ignored in A and B-grade browsers, but is necessary for C-grade browsers. |
Table 4.2 describes a list of hyperlinks that disable the Ajax page transition functionality. These hyperlinks are great for pages on an external domain, pages that open in a new window, linking from single to multi-page templates or linking to pages where you simply don’t want to use Ajax.
Table 4.2 (Link Types that Disable Ajax)
Disabling Ajax
| Hyperlink Markup | Description |
| <a href=”https://www.jquery.com”>Externalhyperlink</a> | Linking to a page on an external domain automatically disables the Ajax functionality. |
| <a href=”https://www.jquery.com”rel=”external”>External hyperlink</a> | By default this attribute defines a hyperlink as external, which not only disables Ajax, but also removes it from the page hash history and refreshes the webpage. This option can be transformed using jQuery to open new windows in a standards-compliant way. |
| <a href=”https://www.jquery.com” data-ajax=”false”>Hyperlink disables Ajax</a> | This option provides a way to define a hyperlink as external, which not only disables Ajax, but also removes it from the page hash history and refreshes the webpage. |
All of these link types stem from a basic HTML hyperlink with the addition of specific attributes.
Table 4.3 (Miscellaneous Link Types)
HTML5 Hyperlinks
| Hyperlink Markup | Description |
| <a href=”tel:15556667777”>Phone Number</a> | This hyperlink will initiate a phone call when clicked on some phones. |
| <a href=”mailto:jdoe@jquerymobile.tv”>Email link</a> | This hyperlink initiates a new email that is pre-filled with the specified email address. |
| <a href=”#”>Hyperlink</a> | This hyperlink will return false. This option is useful when creating a back button as in table 4.1. |
The jQuery Mobile framework utilizes many hyperlink attributes to create enhancements to otherwise normal HTML webpages. This is just another reason why jQuery Mobile is more appealing than creating a mobile website from scratch. It allows you to focus on what matters, eliminating the need to write core functionality every time you create a new mobile website.
The following examples show a few of the link types we just covered in tables 4.1-4.3:
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Single-page template - Page 1 - jQuery Mobile: Design and Develop</title>
<link rel="stylesheet" href="https://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.css" />
<script src="https://code.jquery.com/jquery-1.6.4.min.js"></script>
<script src="https://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.js"></script>
</head>
<body class="container">
<div data-role="page">
<div data-role="header">
<h1>Page 1</h1>
</div>
<div data-role="content">
<p><a href="single-page-2.html">Link to page 2</a></p>
<p><a href="single-page-2.html" rel="external">External Link to page 2</a></p>
<p><a href="single-page-2.html" data-ajax="false">Ajax-disabled link to page 2</a></p>
</div>
<div data-role="footer">
Copyright
</div>
</div>
</body>
</html>
This webpage offers three examples of the link types that can be used in jQuery Mobile; an internal link, an external link and a link that disables Ajax.
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Single-page template - Page 2 - jQuery Mobile: Design and Develop</title>
<link rel="stylesheet" href="https://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.css" />
<script src="https://code.jquery.com/jquery-1.6.4.min.js"></script>
<script src="https://code.jquery.com/mobile/1.0/jquery.mobile-1.0.min.js"></script>
</head>
<body class="container">
<div data-role="page">
<div data-role="header">
<h1>Page 2</h1>
</div>
<div data-role="content">
<p><a href="single-page.html">Ajax link to page 1</a></p>
<p><a href="#" data-rel="back">Back button</a></p>
</div>
<div data-role="footer">
Copyright
</div>
</div>
</body>
</html>
In this example there is an internal link and a hyperlink that acts as a back button.
Wrapping up
Working with Pages is easy with jQuery Mobile, all you really need to know is basic HTML with the addition of a few mobile-related attributes. With most of the heavy lifting being done by the framework it’s easy to focus on the results of the website begin built. Understanding the internal functionality behind how pages work in jQuery Mobile is what begins to set you up for writing your own custom functionality. There is more functionality to Pages, it’s now time to dive even deeper.
