Hopiu/jquery-mobile
1
0
Fork 0
mirror of https://github.com/Hopiu/jquery-mobile.git synced 2026-03-16 22:10:25 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Updated docs to clarify the replaceState known issues and to add docs on the pushStateEnabled option

Browse source
This commit is contained in:
toddparker 2011-10-10 13:14:59 -04:00
parent a589da3936
commit 38e77e5c80
2 changed files with 7 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/api/globalconfig.html
View file

@ -98,15 +98,17 @@ $(document).bind("mobileinit", function(){
<dt><code>ajaxEnabled</code> <em>boolean</em>, default: true</dt>
<dd>jQuery Mobile will automatically handle link clicks and form submissions through Ajax, when possible. If false, url hash listening will be disabled as well, and urls will load as regular http requests.</dd>
<dt><code>hashListeningEnabled</code> <em>boolean</em>, default: true</dt>
<dd>jQuery Mobile will automatically listen and handle changes to the location.hash. Disabling this will prevent jQuery Mobile from handling hash changes, which allows you to handle them yourself, or simply to use simple deep-links within a document that scroll to a particular ID.</dd>
<dt><code>pushStateEnabled</code> <em>boolean</em>, default: true</dt>
<dd>Enhancement to use <code>history.replaceState</code> in supported browsers, to convert the hash-based Ajax URL into the full document path. Note that we <a href="../pages/page-navmodel.html">recommend</a> disabling this feature if Ajax is disabled or if extensive use of external links are used.</dd>
<dt><code>defaultPageTransition</code> <em>string</em>, default: 'slide'</dt>
<dd>Set the default transition for page changes that use Ajax. Set to 'none' for no transitions by default.</dd>
<dt><code>touchOverflowEnabled</code> <em>boolean</em>, default: false</dt>
<dd>Enable pages to have self-contained native scrolling and fixed toolbars in devices that support the <code>overflow-scrolling: touch; </code> property.</dd>
<dd>Enable smoother page transitions and true fixed toolbars in devices that support both the <code>overflow:</code> and <code>overflow-scrolling: touch; </code> CSS properties.</dd>
<dt><code>defaultDialogTransition</code> <em>string</em>, default: 'pop'</dt>
<dd>Set the default transition for dialog changes that use Ajax. Set to 'none' for no transitions by default.</dd>

6
docs/pages/page-navmodel.html
View file

@ -45,13 +45,13 @@
<h2>replaceState plugin</h2>
<p>For those browsers that support <code>history.pushState</code> and <code>history.replaceState</code> an additional optional plugin is provided that will convert the hash change urls mentioned in the previous section into the hashless equivelant. It's important to note that it does indeed convert the hash urls by using <code>history.replaceState</code> as the <code>history.pushState</code> does not produce the desired result in some mobile browsers.</p>
<p>For those browsers that support <code>history.replaceState</code>, an optional plugin is provided that will convert the hash change urls mentioned in the previous section into the full document path which is cleaner and makes the Ajax tracking transparent in the URL structure. This is built as an enhancement on top of the hash-based URL system for Ajax links. For browsers that do not support <code>history.replaceState</code>, or if this feature is disabled, hash-based URLs will be used instead. Note that this feature converts hash-based urls by using <code>history.replaceState</code> (not <code>history.pushState</code>) because this works more reliably across our target platforms. </p>
<p>Since the plugin initializes when the DOM is fully loaded you can enable and disable it manually by setting <code>$.mobile.pushStateEnabled</code> anytime before document ready.</p>
<p>Since the plugin initializes when the DOM is fully loaded you can enable and disable it manually by setting <code>$.mobile.pushStateEnabled</code> global <a href="../api/globalconfig.html">configuration option</a> to <code>false</code> anytime before document ready.</p>
<div class="ui-body ui-body-e">
<h4 style="margin:.5em 0">Important: rel="external" and $.mobile.ajaxEnabled=false</h4>
Many browsers have finicky implementations of the (push|replace)State api which can cause odd behvior in some cases (most often when returning to a document onto which state has been pushed or replaced). When building a jQuery Mobile application where the ajax navigation is being explicityly disabled regularly you may wish to disable pushstate support (see above) across the application and fall back to the hash based navigation for more consistent behaviour.
<p>Slightly different implementations of the replaceState API in various browsers can cause odd behavior in specific scenarios. For example, some browser implementations (including desktop browsers) implement the <code>popstate</code> event differently when linking externally and moving back to a page onto which state has already been pushed/replaced. When building a jQuery Mobile application where the ajax navigation is being explicitly disabled, either though the frequent use of <code>rel="external"</code> on links or by disabling Ajax navigation completely via the <code>$.mobile.ajaxEnabled=false</code>, we recommend disabling the pushState feature to fall back to the hash based navigation for more consistent behavior.</p>
</div>
<h2>changePage</h2>