Permalink
Browse files

Docs: Cleaned up "Prefetching & caching pages" page

Renamed page for consistency and edited/clarified page content
  • Loading branch information...
1 parent 001e588 commit 583289018523d3fee019ff15bba071e3033ca9c1 @globalmatt globalmatt committed Sep 1, 2011
View
@@ -9,3 +9,5 @@ combine/
compiled/
gitstatus.log
refreshCDN
+*.swp
+.gitignore
View
@@ -33,7 +33,7 @@
<li><a href="page-links.html">Linking pages</a></li>
<li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
<li><a href="page-dialogs.html">Dialogs</a></li>
- <li><a href="page-cache.html">Preload & cache pages</a></li>
+ <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
<li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li></li>
<li><a href="page-scripting.html">Scripting pages</a></li>
<li><a href="pages-themes.html">Theming pages</a></li>
@@ -198,7 +198,7 @@
<li><a href="page-links.html">Linking pages</a></li>
<li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
<li><a href="page-dialogs.html">Dialogs</a></li>
- <li><a href="page-cache.html">Preload & cache pages</a></li>
+ <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
<li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li></li>
<li><a href="page-scripting.html">Scripting pages</a></li>
<li><a href="pages-themes.html">Theming pages</a></li>
@@ -216,4 +216,4 @@
</div><!-- /page -->
</body>
- </html>
+ </html>
View
@@ -3,7 +3,7 @@
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
- <title>jQuery Mobile Docs - Preload & cache pages</title>
+ <title>jQuery Mobile Docs - Prefetching &amp; caching pages</title>
<link rel="stylesheet" media="only all" href="../../themes/default/" />
<link rel="stylesheet" href="../_assets/css/jqm-docs.css"/>
<script src="../../js/jquery.js"></script>
@@ -16,54 +16,69 @@
<div data-role="page" class="type-interior">
<div data-role="header" data-theme="f">
- <h1>Preload & cache pages</h1>
+ <h1>Prefetching &amp; caching pages</h1>
<a href="../../" data-icon="home" data-iconpos="notext" data-direction="reverse" class="ui-btn-right jqm-home">Home</a>
</div><!-- /header -->
<div data-role="content">
<div class="content-primary">
- <h2>Pre-fetching pages</h2>
-
- <p>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 <code>data-prefetch</code> 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:</p>
+ <h2>Prefetching pages</h2>
+
+ <p>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.</p>
+
+ <p>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 <code>data-prefetch</code> 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:</p>
<pre><code>
- &lt;a href="foo/bar/baz" data-prefetch&gt;link text&lt;/a&gt;
+&lt;a href="prefetchThisPage.html" data-prefetch&gt; ... &lt;/a&gt;
</code></pre>
+ <p>You can prefetch as many linked pages as you like. Just add <code>data-prefetch</code> to all the links you want to prefetch.</p>
- <p>Technically here's how it works: after pagecreate, jQuery Mobile will automatically find all links in a page that have an attribute of <code>data-prefetch</code> 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.</p>
+ <p>Alternatively, you can prefetch a page programmatically using <code>$.mobile.loadPage()</code>:</p>
+
+<pre><code>
+$.mobile.loadPage( <var>pageUrl</var> );
+</code></pre>
- <p>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.</p>
-
-
-<pre><code> &lt;a href="foo/bar/baz" data-prefetch&gt;link text&lt;/a&gt;</code></pre>
+ <p>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.</p>
- <p>Pages can also be pre-fetched programmatically by calling <code>$.mobile.loadpage( url )</code></p>
+ <p>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.</p>
<h2>DOM size management</h2>
- <p>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.</p>
+ <p>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.</p>
+
+ <p>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.)</p>
+
+ <p>Pages inside a multi-page template aren't affected by this feature at all - jQuery Mobile only removes pages loaded via Ajax.</p>
+
- <p>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.</p>
+ <h2>Caching pages in the DOM</h2>
- <p>A page option called <code>domCache</code> 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, <code>domCache</code> is set to <code>false</code> to keep the DOM size actively managed. If you set this to <code>true</code>, you need to take care to manage the DOM yourself and test thoroughly on a range of devices.</p>
+ <p>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.</p>
- <p>Set the domCache option globally like this:
-<pre><code>$.mobile.page.prototype.options.domCache = true;</code></pre>
+ <p>To keep all previously-visited pages in the DOM, set the <code>domCache</code> option on the page plugin to <code>true</code>, like this:</p>
- <p>To set the domCache option on an individual pages, you can add the <code>data-dom-cache="true"</code> attribute to the page container to tell teh framework to not remove the page when it's hidden:</p>
-<pre><code>&lt;a href="foo/bar/baz" data-dom-cache="true"&gt;link text&lt;/a&gt;
+<pre><code>
+$.mobile.page.prototype.options.domCache = true;
</code></pre>
-
-
- <p>Alternatively, pages can be cached in the DOM programmatically like this:</p>
-<pre><code>elem.page({ domCache: true });</code></pre>
+ <p>Alternatively, to cache just a particular page, you can add the <code>data-dom-cache="true"</code> attribute to the page's container:</p>
+
+<pre><code>
+&lt;div data-role="page" id="cacheMe" data-dom-cache="true"&gt;
+</code></pre>
+ <p>You can also cache a page programmatically like this:</p>
+
+<pre><code>
+<var>pageContainerElement</var>.page({ domCache: true });
+</code></pre>
+ <p>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.</p>
</div><!--/content-primary -->
@@ -84,7 +99,7 @@
<li><a href="page-links.html">Linking pages</a></li>
<li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
<li><a href="page-dialogs.html">Dialogs</a></li>
- <li data-theme="a"><a href="page-cache.html">Preload & cache pages</a></li>
+ <li data-theme="a"><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
<li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li></li>
<li><a href="page-scripting.html">Scripting pages</a></li>
<li><a href="pages-themes.html">Theming pages</a></li>
@@ -102,4 +117,4 @@
</div><!-- /page -->
</body>
- </html>
+ </html>
@@ -86,7 +86,7 @@
<li><a href="page-links.html">Linking pages</a></li>
<li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
<li data-theme="a"><a href="page-dialogs.html">Dialogs</a></li>
- <li><a href="page-cache.html">Preload & cache pages</a></li>
+ <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
<li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li></li>
<li><a href="page-scripting.html">Scripting pages</a></li>
<li><a href="pages-themes.html">Theming pages</a></li>
@@ -104,4 +104,4 @@
</div><!-- /page -->
</body>
-</html>
+</html>
@@ -114,7 +114,7 @@
<li data-theme="a"><a href="page-links.html">Linking pages</a></li>
<li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
<li><a href="page-dialogs.html">Dialogs</a></li>
- <li><a href="page-cache.html">Preload & cache pages</a></li>
+ <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
<li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li></li>
<li><a href="page-scripting.html">Scripting pages</a></li>
<li><a href="pages-themes.html">Theming pages</a></li>
@@ -132,4 +132,4 @@
</div><!-- /page -->
</body>
- </html>
+ </html>
@@ -122,7 +122,7 @@
<li><a href="page-links.html">Linking pages</a></li>
<li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
<li><a href="page-dialogs.html">Dialogs</a></li>
- <li><a href="page-cache.html">Preload & cache pages</a></li>
+ <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
<li data-theme="a"><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li></li>
<li><a href="page-scripting.html">Scripting pages</a></li>
<li><a href="pages-themes.html">Theming pages</a></li>
@@ -105,7 +105,7 @@
<li><a href="page-links.html">Linking pages</a></li>
<li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
<li><a href="page-dialogs.html">Dialogs</a></li>
- <li><a href="page-cache.html">Preload & cache pages</a></li>
+ <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
<li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li>
<li data-theme="a"><a href="page-scripting.html">Scripting pages</a></li>
<li><a href="pages-themes.html">Theming pages</a></li>
@@ -123,4 +123,4 @@
</div><!-- /page -->
</body>
- </html>
+ </html>
@@ -57,7 +57,7 @@
<li><a href="page-links.html">Linking pages</a></li>
<li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
<li><a href="page-dialogs.html">Dialogs</a></li>
- <li><a href="page-cache.html">Preload & cache pages</a></li>
+ <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
<li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li>
<li><a href="page-scripting.html">Scripting pages</a></li>
<li><a href="pages-themes.html">Theming pages</a></li>
@@ -75,4 +75,4 @@
</div><!-- /page -->
</body>
- </html>
+ </html>
@@ -67,7 +67,7 @@
<li><a href="page-links.html">Linking pages</a></li>
<li data-theme="a"><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
<li><a href="page-dialogs.html">Dialogs</a></li>
- <li><a href="page-cache.html">Preload & cache pages</a></li>
+ <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
<li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li></li>
<li><a href="page-scripting.html">Scripting pages</a></li>
<li><a href="pages-themes.html">Theming pages</a></li>
@@ -103,4 +103,4 @@
</div>
</body>
- </html>
+ </html>
@@ -203,7 +203,7 @@
<li><a href="page-links.html">Linking pages</a></li>
<li><a href="page-transitions.html" data-ajax="false">Page transitions</a></li>
<li><a href="page-dialogs.html">Dialogs</a></li>
- <li><a href="page-cache.html">Preload & cache pages</a></li>
+ <li><a href="page-cache.html">Prefetching &amp; caching pages</a></li>
<li><a href="page-navmodel.html">Ajax, hashes &amp; history</a></li>
<li><a href="page-scripting.html">Scripting pages</a></li>
<li data-theme="a"><a href="pages-themes.html">Theming pages</a></li>
@@ -221,4 +221,4 @@
</div><!-- /page -->
</body>
- </html>
+ </html>

0 comments on commit 5832890

Please sign in to comment.