<p>The jQuery Mobile "page" structure is optimized to support either single pages, or local internal linked "pages" within a page.</p>
<p>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.</p>
<p>A jQuery Mobile site must start with an HTML5 'doctype' to take full advantage of all of the framework's features. (Older devices with browsers that don't understand HTML5 will safely ignore the 'doctype' and various custom attributes.) In the 'head', references to jQuery, jQuery Mobile and the mobile theme CSS are all required to start things off:</p>
<p>Inside the <code><body></code> tag, each view or "page" on the mobile device is identified with an element (usually a <code>div</code>) with the <code>data-role="page"</code> attribute:</p>
<p>Within the "page" container, any valid HTML markup can be used, but for typical pages in jQuery Mobile, the immediate children of a "page" are divs with data-roles of <code>"header"</code>, <code>"content"</code>, and <code>"footer"</code>.</p>
<p>By default, when you click on a link that points to an external page (ex. products.html), the framework will parse the link's <code>href</code> to formulate an Ajax request (Hijax) and displays the loading spinner.</p>
<p>If the Ajax request is successful, the new page content is added to the DOM, the <code>mobilize()</code> function runs, then the new page is animated into view with a page transition.</p>
<p>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 <ahref="notapage.html">example of the error message</a>.</p>
<p>A single HTML document can contain multiple 'pages' that are loaded together by stacking multiple divs with a <code>data-role</code> of <code>"page"</code>. Each 'page' block needs a unique ID (<code>id="foo"</code>) that will be used to link internally between 'pages' (<code>href="#foo"</code>). When a link is clicked, the framework will look for an internal 'page' with the ID and transition it into view.</p>
<p>It's important to note if you are linking from a mobile page that was loaded via Ajax to a page with multiple internal pages, you need to add a <code>rel="external"</code> 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 a conflicts.</p>
<p>Here is an example of a 2 "page" site built with two jQuery Mobile divs navigated by linking to an ID placed on each page wrapper. Note that the IDs on the page wrappers are only needed to support the internal page linking, and are optional if each page is a separate HTML document. Here is what two pages look inside the <code>body</code> element.</p>
<p>PLEASE NOTE: Since we are using the hash to track navigation history for all the Ajax 'pages', it's not currently possible to deep link to an anchor (<code>index.html#foo</code>) on a page in jQuery Mobile, because the framework will look for a 'page' with an <code>ID</code> of <code>#foo</code> instead of the native behavior of scrolling to the content with that <code>ID</code>.</p>
