Hopiu/jquery-mobile
1
0
Fork 0
mirror of https://github.com/Hopiu/jquery-mobile.git synced 2026-04-19 05:41:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

edited some nav model info - needs filling out, but outdated info is removed now at least

Browse source
This commit is contained in:
scottjehl 2011-01-26 22:44:32 -05:00
parent 9a492d06fd
commit df05143371
1 changed files with 9 additions and 20 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
docs/pages/docs-navmodel.html
View file

@ -22,7 +22,7 @@
<p>A "page" in jQuery Mobile consists of an element (usually a <code>div</code>) with a <code>data-role</code> attribute set to <code>"page"</code>, which generally contains <code>div</code> elements with roles of <code>"header"</code>, <code>"content"</code>, and <code>"footer"</code>, each containing common markup, forms, and custom jQuery Mobile widgets.</p>
<p>The basic workflow with page loading is as follows: first, a page is requested with a normal HTTP request, and subsequent "pages" are then requested and injected into that page's DOM. Because of this, the DOM may have a number of "pages" in it at a time, each of which can be re-visited by linking to its <code>ID</code> attribute.</p>
<p>The basic workflow with page loading is as follows: first, a page is requested with a normal HTTP request, and subsequent "pages" are then requested and injected into that page's DOM. Because of this, the DOM may have a number of "pages" in it at a time, each of which can be re-visited by linking to its <code>data-url</code> attribute.</p>
<p>When a url is initially requested, there may be one or more "pages" in the response, and only the first one will be shown. The advantage of storing more than one "page" is that it allows you to pre-fetch static pages that are likely to be visited.</p>
@ -52,31 +52,20 @@
<p>jQuery Mobile manages http requests using a combination of generated absolute URL paths and manipulating a generated <code>&lt;base&gt;</code> element's href attribute. The combination of these two approaches allows us to create URLs that contain full path information for loading pages, and a base element to properly direct asset requests made by those loaded pages (such as images and stylesheets).</p>
<p>jQuery Mobile core contains 4 internal functions for manipulating a base url to be used in normalizing relative http requests:</p>
<p><strong>Note: These functions have changed - docs will be updated soon!</strong></p>
<ul>
<li><p>getPathDir: function that returns a path with the last "/"-split segment removed (which is assumed to be a file url).</p></li>
<li><p>getBaseURL: function that returns either the location.hash, or a path specified via its argument, with the last segment removed.</p></li>
<li><p>setBaseURL: sets the <code>&lt;base&gt;</code> element's <code>href</code> attribute to the value of <code>getBaseURL()</code></p></li>
<li><p>resetBaseURL: sets the <code>&lt;base&gt;</code> element's <code>href</code> attribute to the relative path of the initially-http-requested page.</p></li>
</ul><p>These are called at certain times during page requests and transitions:
On DOM ready, during the initial page load, a <code>&lt;base&gt;</code> element is created and appended to the <code>&lt;head&gt;</code> of the page. Immediately after that, <code>resetBaseURL()</code> is called to set the <code>&lt;base&gt;</code> element's href to <code>location.pathname</code>.</p>
<p>Whenever a link with a relative URL is clicked, the <code>$.mobile.changePage()</code> function will prefixed that link's href with the value of <code>getBaseURL()</code>, which creates a full path to that file, relative to the document.</p>
<p>Changing the hash value triggers the hashchange event handler, which first calls <code>resetBaseURL()</code>, and makes an Ajax request to the value of the hash (which is already a full path, requiring no base url). After that request is sent, <code>setBaseURL()</code> is called, which resets the <code>&lt;base&gt;</code> element's <code>href</code> attribute to the value of <code>getBaseURL()</code> and allows any references to images, stylesheets, and scripts within that page to be requested with a proper base path.</p>
<p><strong>TODO: update description of internal base and urlHistory objects</strong></p>
<h2>Auto-generated pages and sub-hash urls</h2>
<p>Some plugins may choose to dynamically break a page's content into separate navigable pages, which can then be reached via deep links. One example of this would be the Listview plugin, which will break a nested UL (or OL) into separate pages, which are each given an ID so they can be linked to like any normal "page" in jQuery Mobile. However, in order to link to these pages, the page that generates them must first be requested from the server. To make this work, pages that are auto-generated by plugins use the following special ID structure:
<code>&lt;div id="page.html&amp;subpageidentifier"&gt;</code></p>
<p>Some plugins may choose to dynamically break a page's content into separate navigable pages, which can then be reached via deep links. One example of this would be the Listview plugin, which will break a nested UL (or OL) into separate pages, which are each given a data-url attribute so they can be linked to like any normal "page" in jQuery Mobile. However, in order to link to these pages, the page that generates them must first be requested from the server. To make this work, pages that are auto-generated by plugins use the following special data-url structure:
<code>&lt;div data-url="page.html&amp;subpageidentifier"&gt;</code></p>
<p>So, for example, a page generated by the listview plugin may have an ID like this: <code>id="artists.html&amp;ui-page=listview-1"</code></p>
<p>So, for example, a page generated by the listview plugin may have an data-url attribute like this: <code>data-url="artists.html&amp;ui-page=listview-1"</code></p>
<p>When a page is requested, jQuery Mobile knows to split the URL at "&amp;ui-page" and make an HTTP request to the portion of the URL before that key. In the case of the listview example mentioned above, the URL would look like this: http://example.com/artists.html&amp;ui-page=listview-1
...and jQuery Mobile would request artists.html, which would then generate its sub-pages, creating the div with id="artists.html&amp;ui-page=listview-1", which it will then display as the active page.</p>
...and jQuery Mobile would request artists.html, which would then generate its sub-pages, creating the div with data-url="artists.html&amp;ui-page=listview-1", which it will then display as the active page.</p>
<p><em>Note that the ID of the element contains the full URL path, not just the portion after &amp;ui-page=. This allows jQuery Mobile to use a single consistent mechanism that matches URLs to page IDs.</em></p>
<p><em>Note that the data-url attribute of the element contains the full URL path, not just the portion after &amp;ui-page=. This allows jQuery Mobile to use a single consistent mechanism that matches URLs to page data-url attributes.</em></p>
<h2>Cases when Ajax navigation will not be used</h2>
@ -96,7 +85,7 @@
<ul>
<li><p>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.</p></li>
<li><p>Any unique assets referenced by pages in a jQuery Mobile-driven site should be placed inside the "page" element (the element with a data-role attribute of "page"). For example, links to styles and scripts that are specific to a particular page can be referenced inside that div. However, a better approach is to use jQuery Mobile's page events to trigger specific scripting when certain pages load.</p></li>
<li><p>Any unique assets referenced by pages in a jQuery Mobile-driven site should be placed inside the "page" element (the element with a data-role attribute of "page"). For example, links to styles and scripts that are specific to a particular page can be referenced inside that div. However, a better approach is to use jQuery Mobile's page events to trigger specific scripting when certain pages load. <strong>Note: </strong> you can return a page from the server with a data-url already specified in the markup, and jQuery Mobile will use that for the hash update. This allows you to ensure directory paths resolve with a trailing slash and will therefore be used in the base url path for future requests.</p></li>
<li><p>Conversely, any non-unique assets (those used site-wide) should be referenced in the <code>&lt;head&gt;</code> section of an HTML document, or at the very least, outside of the "page" element, to prevent running scripts more than once.</p></li>
<li><p>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 <code>jQuery.mobile.subPageUrlKey</code>.</p></li>
</ul>