Links API

jQuery Mobile is designed to work with standard page link conventions and layers the AJAX navigation on top for maximum compatibility.

Linking pages

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 nav 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.

Default link behavior: AJAX

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 is done 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: You cannot link to a 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.

Linking without AJAX

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.

In version 1.1, we added support for using data-ajax="false" on a parent container which allows you to exclude a large number of links from the AJAX navigation system. This avoids the need to add this attribute to every link in a container. To activate this functionality, $.mobile.ignoreContentEnabled must be set to true because this feature adds overhead we don't want to enable by default.

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.

Linking within a multi-page document

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>

"Back" button links

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. Note: data-direction="reverse" is meant to simply run the backwards version of the transition that will run on that page change, while data-rel="back" makes the link functionally equivalent to the browser's back button and all the standard back button logic applies. Adding data-direction="reverse" to a link with data-rel="back" will not reverse the reversed page transition and produce the "normal" version of the transition.

Redirects and linking to directories

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.

Link notes

The non-standard environment created by jQuery Mobile's page navigation model introduces some conditions of which you should be aware when building pages:

• When linking to directories, without a filename URL, (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.

• Documents loaded via AJAX will select the first page in the DOM of that document to be loaded as a jQuery Mobile page element. As a result the developer must make sure to manage the id attributes of the loaded page and child elements to prevent confusion when manipulating the DOM.

• If you link to a multipage document, you must use a data-ajax="false" attribute on the link to cause a full page refresh due to the limitation above where we only load the first page node in an AJAX request due to potential hash collisions. There is currently a subpage plugin that makes it possible to load in multipage documents.

• While linking pages inside a multipage template, you should not use the data-ajax="false" attribute as it is of no use and will only interfere with the transition settings.

• The "ui-page" key name used in sub-hash URL references can be set to any value you'd like, so as to blend into your URL structure. This value is stored in jQuery.mobile.subPageUrlKey.

• When traveling back to a previously loaded jQuery Mobile document from an external or internal document with the push state plugin enabled, some browsers load and trigger the popstate event on the wrong document or for the wrong reasons (two edge cases recorded so far). If you are regularly linking to external documents and find the application behaving erratically try disabling pushstate support.

• jQuery Mobile does not support query parameter passing to internal/embedded pages but there are two plugins that you can add to your project to support this feature. There is a lightweight page params plugin and a more fully featured jQuery Mobile router plugin for use with backbone.js or spine.js. A newer plugin called routerlite keeps it simple with just four methods: routeinit, routechange, pageinit and pagechange.

• Some external applications (notably Facebook's OAuth implementation) modify their response URL in such a way that interferes with jQuery Mobile. In particular, Facebook appends #_=_ to the end of the callback. Currently the best solution for this is to remove it from the location hash before jQuery Mobile loads using something like: if (window.location.hash == "#_=_") window.location.hash = ""; . jQuery Mobile can then process & enhance the page properly.