diff --git a/.gitignore b/.gitignore index e3a53d48..a73ae101 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,5 @@ combine/ compiled/ gitstatus.log refreshCDN +*.swp +.gitignore diff --git a/docs/pages/index.html b/docs/pages/index.html index cf4d7fcc..8c205de9 100755 --- a/docs/pages/index.html +++ b/docs/pages/index.html @@ -33,7 +33,7 @@
  • Linking pages
  • Page transitions
  • Dialogs
    • -
  • Preload & cache pages
    • +
  • Prefetching & caching pages
  • Ajax, hashes & history
  • Scripting pages
  • Theming pages
    • diff --git a/docs/pages/page-anatomy.html b/docs/pages/page-anatomy.html index dada5ba6..28682974 100644 --- a/docs/pages/page-anatomy.html +++ b/docs/pages/page-anatomy.html @@ -198,7 +198,7 @@
  • Linking pages
  • Page transitions
  • Dialogs
    • -
  • Preload & cache pages
    • +
  • Prefetching & caching pages
  • Ajax, hashes & history
  • Scripting pages
  • Theming pages
    • @@ -216,4 +216,4 @@ - \ No newline at end of file + diff --git a/docs/pages/page-cache.html b/docs/pages/page-cache.html index 09bb2a40..a5005f5a 100644 --- a/docs/pages/page-cache.html +++ b/docs/pages/page-cache.html @@ -3,7 +3,7 @@ - jQuery Mobile Docs - Preload & cache pages + jQuery Mobile Docs - Prefetching & caching pages @@ -16,7 +16,7 @@
    -

    Preload & cache pages

    +

    Prefetching & caching pages

    Home
    @@ -24,46 +24,61 @@
    -

    Pre-fetching pages

    - -

    If you're using a single page template, but would prefer to lazy load in a few key pages in the background to avoid seeing the Ajax loader, we recommend using the pre-fetch feature instead of moving to a multi-page template. To pre-fetch a page, simply add the data-prefetch attribute to any link and jQuery Mobile will lazy load this page in the background after the primary page has loaded. Here's an example:

    +

    Prefetching pages

    + +

    Usually, it's a good idea to store your app's pages in several single-page templates instead of one large multi-page template. This minimizes the size of the page's DOM.

    + +

    When using single-page templates, you can prefetch pages into the DOM so that they're available instantly when the user visits them. To prefetch a page, add the data-prefetch attribute to a link that points to the page. jQuery Mobile then loads the target page in the background after the primary page has loaded and the pagecreate event has triggered. For example:

    
- <a href="foo/bar/baz" data-prefetch>link text</a>
+<a href="prefetchThisPage.html" data-prefetch> ... </a>
    +

    You can prefetch as many linked pages as you like. Just add data-prefetch to all the links you want to prefetch.

    -

    Technically here's how it works: after pagecreate, jQuery Mobile will automatically find all links in a page that have an attribute of data-prefetch and automatically load the pages so they're available as soon as the user clicks on the link. The Ajax loader won't appear unless the framework hasn't loaded the page by the time the link was clicked.

    +

    Alternatively, you can prefetch a page programmatically using $.mobile.loadPage():

    + +
    
+$.mobile.loadPage( pageUrl );
+
    -

    Pre-fetching links will naturally cause additional HTTP requests and increased bandwidth that may never be used, so it's important to use this feature only in situations where it's highly likely that a page will be visited.

    - - -
     <a href="foo/bar/baz" data-prefetch>link text</a>
    +

    Another advantage of prefetching a page is that the user doesn't see the Ajax loading message when visiting the prefetched page. The Ajax loading message only appears if the framework hasn't finished prefetching the page by the time the link is followed.

    -

    Pages can also be pre-fetched programmatically by calling $.mobile.loadpage( url )

    +

    Prefetching pages naturally creates additional HTTP requests and uses bandwidth, so it's wise to use this feature only in situations where it's highly likely that the prefetched page will be visited. A common scenario is a photo gallery, where you can prefetch the "previous" and "next" photo pages so that the user can move quickly between photos.

    DOM size management

    -

    Since animated page transitions require that the page you're on and the one you're transitioning to are both in the DOM, we add pages to the DOM as you navigate around. Before Beta 2, those pages would continue to stay in the DOM until a full page refresh occured so there was always a concern that we could hit a memory ceiling on some devices and cause the browser to slow down or even crash.

    +

    For animated page transitions to work, the pages you're transitioning from and to both need to be in the DOM. However, keeping old pages in the DOM quickly fills the browser's memory, and can cause some mobile browsers to slow down or even crash.

    -

    The jQuery Mobile framework has a simple mechanism to keep the DOM tidy: whenever a page is loaded in via Ajax, it is flagged for removal from the DOM once you navigate away to another page (technically, on pagehide). If you return to a deleted page, the browser may be able to retrieve the file from it's cache, or it will re-request it fro the sever if needed. In the case of nested lists, we remove all the pages that make up the nested list once you navigate to a page that's not part of the list. Pages that are included in a multi-page setup won't be affected by this feature at all - only pages brought in by Ajax are managed this way by jQuery Mobile.

    +

    jQuery Mobile therefore has a simple mechanism to keep the DOM tidy. Whenever it loads a page via Ajax, jQuery Mobile flags the page to be removed from the DOM when you navigate away from it later (technically, on the pagehide event). If you revisit a removed page, the browser may be able to retrieve the page's HTML file from its cache. If not, it refetches the file from the server. (In the case of nested list views, jQuery Mobile removes all the pages that make up the nested list once you navigate to a page that's not part of the list.)

    + +

    Pages inside a multi-page template aren't affected by this feature at all - jQuery Mobile only removes pages loaded via Ajax.

    -

    A page option called domCache controls whether to leave pages in the DOM as a way to cache them (the way things used to work) or keep the DOM clean and remove hidden pages (the new way). By default, domCache is set to false to keep the DOM size actively managed. If you set this to true, you need to take care to manage the DOM yourself and test thoroughly on a range of devices.

    -

    Set the domCache option globally like this: -

    $.mobile.page.prototype.options.domCache = true;
    +

    Caching pages in the DOM

    -

    To set the domCache option on an individual pages, you can add the data-dom-cache="true" attribute to the page container to tell teh framework to not remove the page when it's hidden:

    -
    <a href="foo/bar/baz" data-dom-cache="true">link text</a>
+    
    If you prefer, you can tell jQuery Mobile to keep previously-visited pages in the DOM instead of removing them. This lets you cache pages so that they're available instantly if the user returns to them.
    
+
+		
    To keep all previously-visited pages in the DOM, set the domCache option on the page plugin to true, like this:
    
+
+
    
+$.mobile.page.prototype.options.domCache = true;
 
    
 
-		
-		
-		
    Alternatively, pages can be cached in the DOM programmatically like this:
    
-
    elem.page({ domCache: true });
    
+		
    Alternatively, to cache just a particular page, you can add the data-dom-cache="true" attribute to the page's container:
    
 
+
    
+<div data-role="page" id="cacheMe" data-dom-cache="true">
+
    
 
+		
    You can also cache a page programmatically like this:
    
+
+
    
+pageContainerElement.page({ domCache: true });
+
    
+
+    
    The drawback of DOM caching is that the DOM can get very large, resulting in slowdowns and memory issues on some devices. If you enable DOM caching, take care to manage the DOM yourself and test thoroughly on a range of devices.
    @@ -84,7 +99,7 @@
  • Linking pages
  • Page transitions
  • Dialogs
    • -
  • Preload & cache pages
    • +
  • Prefetching & caching pages
  • Ajax, hashes & history
  • Scripting pages
  • Theming pages
    • @@ -102,4 +117,4 @@
    - \ No newline at end of file + diff --git a/docs/pages/page-dialogs.html b/docs/pages/page-dialogs.html index ea78e2dc..a245ed26 100755 --- a/docs/pages/page-dialogs.html +++ b/docs/pages/page-dialogs.html @@ -86,7 +86,7 @@
  • Linking pages
  • Page transitions
  • Dialogs
    • -
  • Preload & cache pages
    • +
  • Prefetching & caching pages
  • Ajax, hashes & history
  • Scripting pages
  • Theming pages
    • @@ -104,4 +104,4 @@ - \ No newline at end of file + diff --git a/docs/pages/page-links.html b/docs/pages/page-links.html index e7b5ea53..c7892158 100755 --- a/docs/pages/page-links.html +++ b/docs/pages/page-links.html @@ -114,7 +114,7 @@
  • Linking pages
  • Page transitions
  • Dialogs
    • -
  • Preload & cache pages
    • +
  • Prefetching & caching pages
  • Ajax, hashes & history
  • Scripting pages
  • Theming pages
    • @@ -132,4 +132,4 @@ - \ No newline at end of file + diff --git a/docs/pages/page-navmodel.html b/docs/pages/page-navmodel.html index cf6081c9..ef27522f 100644 --- a/docs/pages/page-navmodel.html +++ b/docs/pages/page-navmodel.html @@ -122,7 +122,7 @@
  • Linking pages
  • Page transitions
  • Dialogs
    • -
  • Preload & cache pages
    • +
  • Prefetching & caching pages
  • Ajax, hashes & history
  • Scripting pages
  • Theming pages
    • diff --git a/docs/pages/page-scripting.html b/docs/pages/page-scripting.html index dca84279..c6205f44 100644 --- a/docs/pages/page-scripting.html +++ b/docs/pages/page-scripting.html @@ -105,7 +105,7 @@ $.mobile.silentScroll(300);
  • Linking pages
  • Page transitions
  • Dialogs
    • -
  • Preload & cache pages
    • +
  • Prefetching & caching pages
  • Ajax, hashes & history
  • Scripting pages
  • Theming pages
    • @@ -123,4 +123,4 @@ $.mobile.silentScroll(300); - \ No newline at end of file + diff --git a/docs/pages/page-titles.html b/docs/pages/page-titles.html index 2f7c7174..23e53410 100644 --- a/docs/pages/page-titles.html +++ b/docs/pages/page-titles.html @@ -57,7 +57,7 @@
  • Linking pages
  • Page transitions
  • Dialogs
    • -
  • Preload & cache pages
    • +
  • Prefetching & caching pages
  • Ajax, hashes & history
  • Scripting pages
  • Theming pages
    • @@ -75,4 +75,4 @@ - \ No newline at end of file + diff --git a/docs/pages/page-transitions.html b/docs/pages/page-transitions.html index 451ccfb4..aa602bea 100755 --- a/docs/pages/page-transitions.html +++ b/docs/pages/page-transitions.html @@ -67,7 +67,7 @@
  • Linking pages
  • Page transitions
  • Dialogs
    • -
  • Preload & cache pages
    • +
  • Prefetching & caching pages
  • Ajax, hashes & history
  • Scripting pages
  • Theming pages
    • @@ -103,4 +103,4 @@ - \ No newline at end of file + diff --git a/docs/pages/pages-themes.html b/docs/pages/pages-themes.html index bcc02614..10735802 100755 --- a/docs/pages/pages-themes.html +++ b/docs/pages/pages-themes.html @@ -203,7 +203,7 @@
  • Linking pages
  • Page transitions
  • Dialogs
    • -
  • Preload & cache pages
    • +
  • Prefetching & caching pages
  • Ajax, hashes & history
  • Scripting pages
  • Theming pages
    • @@ -221,4 +221,4 @@ - \ No newline at end of file +