From 38e77e5c802bf3bf5ffb346c2a02b0705d79d23d Mon Sep 17 00:00:00 2001 From: toddparker Date: Mon, 10 Oct 2011 13:14:59 -0400 Subject: [PATCH] Updated docs to clarify the replaceState known issues and to add docs on the pushStateEnabled option --- docs/api/globalconfig.html | 6 ++++-- docs/pages/page-navmodel.html | 6 +++--- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/api/globalconfig.html b/docs/api/globalconfig.html index 6dba4c7e..a9444d1b 100755 --- a/docs/api/globalconfig.html +++ b/docs/api/globalconfig.html @@ -98,15 +98,17 @@ $(document).bind("mobileinit", function(){
ajaxEnabled boolean, default: true
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.
-
hashListeningEnabled boolean, default: true
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.
+ +
pushStateEnabled boolean, default: true
+
Enhancement to use history.replaceState in supported browsers, to convert the hash-based Ajax URL into the full document path. Note that we recommend disabling this feature if Ajax is disabled or if extensive use of external links are used.
defaultPageTransition string, default: 'slide'
Set the default transition for page changes that use Ajax. Set to 'none' for no transitions by default.
touchOverflowEnabled boolean, default: false
-
Enable pages to have self-contained native scrolling and fixed toolbars in devices that support the overflow-scrolling: touch; property.
+
Enable smoother page transitions and true fixed toolbars in devices that support both the overflow: and overflow-scrolling: touch; CSS properties.
defaultDialogTransition string, default: 'pop'
Set the default transition for dialog changes that use Ajax. Set to 'none' for no transitions by default.
diff --git a/docs/pages/page-navmodel.html b/docs/pages/page-navmodel.html index 919a02e6..584a3563 100644 --- a/docs/pages/page-navmodel.html +++ b/docs/pages/page-navmodel.html @@ -45,13 +45,13 @@

replaceState plugin

-

For those browsers that support history.pushState and history.replaceState 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 history.replaceState as the history.pushState does not produce the desired result in some mobile browsers.

+

For those browsers that support history.replaceState, 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 history.replaceState, or if this feature is disabled, hash-based URLs will be used instead. Note that this feature converts hash-based urls by using history.replaceState (not history.pushState) because this works more reliably across our target platforms.

-

Since the plugin initializes when the DOM is fully loaded you can enable and disable it manually by setting $.mobile.pushStateEnabled anytime before document ready.

+

Since the plugin initializes when the DOM is fully loaded you can enable and disable it manually by setting $.mobile.pushStateEnabled global configuration option to false anytime before document ready.

Important: rel="external" and $.mobile.ajaxEnabled=false

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

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 popstate 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 rel="external" on links or by disabling Ajax navigation completely via the $.mobile.ajaxEnabled=false, we recommend disabling the pushState feature to fall back to the hash based navigation for more consistent behavior.

changePage