Skip to content

Commit

Permalink
Updated docs from $.changePage() to $.mobile.changePage(). Fixes jque…
Browse files Browse the repository at this point in the history
  • Loading branch information
Todd Parker committed Nov 17, 2010
1 parent 061edec commit bf0a32f
Showing 1 changed file with 5 additions and 5 deletions.
10 changes: 5 additions & 5 deletions docs/pages/docs-navmodel.html
Expand Up @@ -33,19 +33,19 @@ <h2>Ajax-driven page navigation</h2>

<p>In general, hash changes are created whenever a link is clicked in jQuery mobile. When a link is clicked, jQuery mobile will make sure the link is referencing a local URL, and if so, it'll prevent the link's default click behavior from occurring and request the referenced url via Ajax instead. When the page returns successfully, it will set the location.hash to the new page's relative url. </p>

<p>Within the framework, page changes - both for pages already in the DOM and for pages that need to be loaded via Ajax - use the $.changePage function. $.changePage contains all of the logic for finding pages to transition to and from, and how to handle various response conditions such as a page not found. $.changePage can be called externally and accepts the following arguments (to, transition, back, changeHash). The <code>to</code> argument can accept either a string (such as a file url or local element's ID), an array (in which the first array item is any local page you'd like to transition from, and the second array item is the <code>to</code> page), or an object (with expected properties: url, type ("get" or "post"), and data (for serialized parameters)), the latter of which is useful for loading pages that expect form data. The <code>transition</code> argument accepts a string representing a named transition, such as "slide". The <code>back</code> argument accepts a boolean representing whether the transition should go forward or in reverse. Lastly, the <code>changeHash</code> argument accepts a boolean for whether you'd like the url to be updated upon a successful page change.</p>
<p>Within the framework, page changes - both for pages already in the DOM and for pages that need to be loaded via Ajax - use the <code>$.mobile.changePage()</code> function. <code>$.mobile.changePage()</code> contains all of the logic for finding pages to transition to and from, and how to handle various response conditions such as a page not found. <code>$.mobile.changePage()</code> can be called externally and accepts the following arguments (to, transition, back, changeHash). The <code>to</code> argument can accept either a string (such as a file url or local element's ID), an array (in which the first array item is any local page you'd like to transition from, and the second array item is the <code>to</code> page), or an object (with expected properties: url, type ("get" or "post"), and data (for serialized parameters)), the latter of which is useful for loading pages that expect form data. The <code>transition</code> argument accepts a string representing a named transition, such as "slide". The <code>back</code> argument accepts a boolean representing whether the transition should go forward or in reverse. Lastly, the <code>changeHash</code> argument accepts a boolean for whether you'd like the url to be updated upon a successful page change.</p>

<p>The $.changePage function is used in a number of places in jQuery Mobile. For example, when a link is clicked, its href attribute is normalized and then $.changePage handles the rest. When forms are submitted, jQuery Mobile simply gathers a few of the form's attributes, serializes its data, and once again, $.changePage is used to handle the submission and response. Also, links that create dialogs use $.changePage to open a referenced page without updating the hash, which is useful for keeping dialogs out of history tracking. </p>
<p>The <code>$.mobile.changePage()</code> function is used in a number of places in jQuery Mobile. For example, when a link is clicked, its href attribute is normalized and then <code>$.mobile.changePage()</code> handles the rest. When forms are submitted, jQuery Mobile simply gathers a few of the form's attributes, serializes its data, and once again, <code>$.mobile.changePage()</code> is used to handle the submission and response. Also, links that create dialogs use <code>$.mobile.changePage()</code>to open a referenced page without updating the hash, which is useful for keeping dialogs out of history tracking. </p>

<p>Another key ingredient to jQuery Mobile's page navigation model is the <code>base</code> element, which is injected into the <code>head</code> and modified on every page change to ensure that any assets (css,images,js,etc) referenced on that page will be requested from a proper path. In browsers that don't support dynamic updates to the <code>base</code> element (such as Firefox 3.6), jQuery Mobile loops through all of the referenced assets on the page and prefixes their href and src attributes with the base path.</p>



<p>Hash changes that occur independently of a click, such as when a user clicks the back button, are handled through the hashchange event, which is bound to the window object using Ben Alman's hashchange special event plugin (included in jQuery Mobile). When a hash change occurs (and also when the first page loads), the hashchange event handler will send the location.hash to the $.changePage function, which in turn either loads or reveals the referenced page.</p>
<p>Hash changes that occur independently of a click, such as when a user clicks the back button, are handled through the hashchange event, which is bound to the window object using Ben Alman's hashchange special event plugin (included in jQuery Mobile). When a hash change occurs (and also when the first page loads), the hashchange event handler will send the location.hash to the <code>$.mobile.changePage()</code> function, which in turn either loads or reveals the referenced page.</p>



<p>Once the referenced page is present in the DOM, the $.changePage function applies a transition between the current active page and the new page. Page transitions happen through adding and removing classes that apply CSS animations. For example, in a slide-left transition, the exiting page is given the classes "slideleft" and "out", and the entering page is given the classes <code>"slideleft"</code> and <code>"in"</code>, as well as a class of <code>"ui-page-active"</code> to mark it as the new "active" page being viewed. When the animation is complete, the <code>"in"</code> and <code>"out"</code> classes are removed, and the exited page loses its <code>"ui-page-active"</code> class.</p>
<p>Once the referenced page is present in the DOM, the <code>$.mobile.changePage()</code> function applies a transition between the current active page and the new page. Page transitions happen through adding and removing classes that apply CSS animations. For example, in a slide-left transition, the exiting page is given the classes "slideleft" and "out", and the entering page is given the classes <code>"slideleft"</code> and <code>"in"</code>, as well as a class of <code>"ui-page-active"</code> to mark it as the new "active" page being viewed. When the animation is complete, the <code>"in"</code> and <code>"out"</code> classes are removed, and the exited page loses its <code>"ui-page-active"</code> class.</p>

<h2>Developer explanation of base url management:</h2>

Expand All @@ -61,7 +61,7 @@ <h2>Developer explanation of base url management:</h2>
</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 $.changePage 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>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>

Expand Down

0 comments on commit bf0a32f

Please sign in to comment.