jQuery Mobile is designed to work with simple page linking conventions. Essentially, you can link pages and assets as you normally would, and jQuery Mobile will automatically handle page requests in a single-page model, using Ajax when possible. When Ajax isn't possible (such as a non-same-domain url, or if specified using certain attributes on the link), a normal http request is used instead.
The goal of this model is to allow developers to create websites using best practices — where ordinary links will "just work" without any special configuration — while creating a rich, native-like experience that can't be achieved with standard HTTP requests.
To enable animated page transitions, all links that point to an external page (ex. products.html) will be loaded via Ajax. To do this unobtrusively, the framework parses the link's href to formulate an Ajax request (Hijax) and displays the loading spinner. All this happens automatically by jQuery Mobile.
If the Ajax request is successful, the new page content is added to the DOM, all mobile widgets are auto-initialized, then the new page is animated into view with a page transition.
If the Ajax request fails, the framework will display a small error message overlay (styled in the "e" swatch) that disappears after a brief time so this doesn't break the navigation flow. View an example of the error message.
Note: that you cannot link to multipage document with Ajax navigation active because the framework will only load the first page it finds, not the full set of internal pages. In these cases, you must link without Ajax (see next section) for a full page refresh to prevent potential hash collisions. There is currently a subpage plugin that makes it possible to load in multi-page documents.
Links that point to other domains or that have rel="external", data-ajax="false" or target attributes will not be loaded with Ajax. Instead, these links will cause a full page refresh with no animated transition. Both attributes (rel="external" and data-ajax="false") have the same effect, but a different semantic meaning: rel="external" should be used when linking to another site or domain, while data-ajax="false" is useful for simply opting a page within your domain from being loaded via Ajax. Because of security restrictions, the framework always opts links to external domains out of the Ajax behavior.
Note: When building a jQuery Mobile application where the Ajax navigation system is disabled globally or frequently disabled on individual links, we recommend disabling the $.mobile.pushStateEnabled global configuration option to avoid inconsistent navigation behavior in some browsers.
A single HTML document can contain one or many 'page' containers simply by stacking multiple divs with a data-role of "page". This allows you to build a small site or application within a single HTML document; jQuery Mobile will simply display the first 'page' it finds in the source order when the page loads.
If a link in a multi-page document points to an anchor (#foo), the framework will look for a page wrapper with that ID (id="foo"). If it finds a page in the HTML document, it will transition the new page into view. You can seamlessly navigate between local, internal "pages" and external pages in jQuery Mobile. Both will look the same to the end user except that external pages will display the Ajax spinner while loading. In either situation, jQuery Mobile updates the page's URL hash to enable Back button support, deep-linking and bookmarking.
It's important to note that if you are linking from a mobile page that was loaded via Ajax to a page that contains multiple internal pages, you need to add a rel="external" or data-ajax="false" to the link. This tells the framework to do a full page reload to clear out the Ajax hash in the URL. This is critical because Ajax pages use the hash (#) to track the Ajax history, while multiple internal pages use the hash to indicate internal pages so there will be conflicts in the hash between these two modes.
For example, a link to a page containing multiple internal pages would look like this:
<a href="multipage.html" rel="external">Multi-page link</a>
If you use the attribute data-rel="back" on an anchor, any clicks on that anchor will mimic the back button, going back one history entry and ignoring the anchor's default href. This is particularly useful when generating "back" buttons with JavaScript, such as a button to close a dialog. When using this feature in your source markup, although browsers that support this feature will not use the specified href attribute, be sure to still provide a meaningful value that actually points to the URL of the referring page to allow the feature to work for users in C-Grade browsers. If users can reach this page from more than one referring pages, specify a sensible href so that the navigation remains logical for all users. Also, please keep in mind that if you just want a reverse transition without actually going back in history, you should use the data-direction="reverse" attribute instead.
When linking to directory indexes (such as href="typesofcats/" instead of href="typesofcats/index.html"), you must provide a trailing slash. This is because jQuery Mobile assumes the section after the last "/" character in a url is a filename, and it will remove that section when creating base urls from which future pages will be referenced.
However, you can work around this issue by returning your page div with a data-url attribute already specified. When you do this, jQuery Mobile will use that attribute's value for updating the URL, instead of the url used to request that page. This also allows you to return urls that change as the result of a redirect, for example, you might post a form to "/login.html" but return a page from the url "/account" after a successful submission. This tool allows you to take control of the jQuery Mobile history stack in these situations. Here's an example:
The following link points to "docs-links-urltest/index.html": Test Link which is a directory with an index page. The return page will update the hash as "/docs/pages/docs-links-urltest/" with a trailing slash. This is done via the data-url attribute in that page's source. Keep in mind that the value will replace the entire hash, and it is up to you to replace it with a URL that actually resolves to the correct page when requested via refresh or deep link.
Learn more about the technical details of the navigation model and Ajax, hashes and history in jQuery mobile.
All standard HTML link types are supported in jQuery Mobile in addition to the types outlined above. Here is a sampler of many common link types: