forked from shinypb/appcachefacts
/
index.html
224 lines (201 loc) · 10.6 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
<!DOCTYPE html>
<html>
<head>
<title>Appcache Facts</title>
<style>
body {
font: 16px/1em 'gill sans', helvetica, sans-serif;
margin: 1em auto;
width: 700px;
}
h1#title, #footer, #facts .details {
border-color: #9bf;
border-style: solid;
border-width: 0;
}
h1#title, #footer {
position: fixed;
width: 710px;
}
h1#title {
border-bottom-width: 1px;
padding-bottom: 0.5em;
text-align: center;
top: 0;
background-color: #fff;
margin: 0;
padding: 20px 0;
}
p#tagline {
margin-top: 70px;
}
#sample {
margin-bottom: 75px;
}
#footer {
border-top-width: 1px;
text-align: center;
bottom: 0;
background-color: #fff;
}
pre, code {
background: #ddd;
font: 0.9em/1em courier, monospace;
}
#facts .details pre, #facts .details code {
background: #e1e3e6;
}
pre {
border-radius: 1em;
padding: 1em;
margin: 0;
}
#facts {
}
li {
margin-top: 1em;
}
li:first-child {
margin-top: 0;
}
#facts li:before {
content: 'Fact: ';
font-weight: bold;
}
#facts .details {
background: #eff4ff;
border-left-width: 1px;
padding: 1em;
margin: 12px 0;
-webkit-border-radius: 5px;
-webkit-box-shadow: 0 0 8px #ccc;
}
#facts .details p:first-child {
margin-top: 0;
}
#facts .details p:last-child {
margin-bottom: 0;
}
em {
color: red;
}
</style>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-21977918-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<h1 id="title">Appcache Facts</h1>
<p id="tagline">The application cache is a poorly understood part of the HTML5 specification with a lot of potential. Let's get rid of
some of the confusion and make the web a faster place.</p>
<section id="facts">
<ul>
<li>Appcache was intended to let your web app run offline, no Internet connection required, but it can also be used online to dramatically decrease load times.</li>
<li>The manifest file must be served with the MIME type <code>text/cache-manifest</code>.
<div class="details">
<p>The suggested file extension for manifests is <code>.appcache</code>.</p>
</div>
</li>
<li>
Appcache manifests have three optional sections: <code>CACHE</code>, <code>NETWORK</code>, and <code>FALLBACK</code>.
<div class="details">
<p>The <code>CACHE</code> section lists all resources that should be downloaded and stored locally. The browser will
begin downloading these in the background as soon as the page has loaded. If any are already in the browser's cache,
they will not be downloaded again separately.</p>
<p>The <code>NETWORK</code> section lists all URLs that may be loaded over the Internet. If your application includes
any API calls, make sure to enumerate them here. Note that this is a list of URL <strong>prefixes</strong>, so if
all of your network calls begin with http://example.com/api/, that's all you need to include.</p>
<p>If you want to allow arbitrary URLs to be accessed (scripts, stylesheets, API calls, anything), include <code>*</code>, <code>http://*</code> and <code>https://*</code> in this section. (Chrome and Safari respect the <code>*</code>; Firefox needs the <code>http://*</code> and <code>https://*</code>.)</p>
<p>The <code>FALLBACK</code> section lists replacements for network URLs to be used when the browser is offline or the
remote server is unavailable.</p>
</div>
</li>
<li>
Over SSL, all resources in the manifest must respect the same-origin policy.
<div class="details">
<p>That is, all paths must be relative, or point to resources on the same host and port as the current page.</p>
<p>The exception is Google Chrome, which doesn't follow the <a href="http://www.w3.org/TR/html5/offline.html">specification</a> in this regard. Over SSL, Chrome will load resources from different origins so long as they are still served over SSL.</p>
</div>
</li>
<li>Any changes made to the manifest file will cause the browser to update the application cache.
<div class="details">
<p>If your resources are going to be located at the same URL even when you upload a new version of them,
add a comment to the manifest file with a changing version number in it.</p>
<p><pre>CACHE MANIFEST
# version 1
CACHE
/logo.png
...</pre></p>
<p>Any line that starts with a <code>#</code> is a comment and will be ignored, but is sufficient to trigger an update when it changes.</p>
</div>
</li>
<li>When updating an existing appcache, the browser sends standard If-Modified-Since headers, so it skips re-downloading files that have not changed.
<div class="details">
If you've just <code>touch</code>ed the manifest file, the browser won't bother to re-check the assets — the contents of the manifest file must change somehow. Modifying a comment is good enough, which is why we recommend having a <code># version</code> line.
</div>
</li>
<li>Any changes made to the manifest or any of its files will not take effect until the next
page load.
<div class="details">
<p>This is because once the page has been appcached, it is immediately served from that
cache the next time the user returns. The browser then checks the manifest for any changes
and downloads any required files in the background. The newest version will be available
on the next load of the page.</p>
<p>If you'd like, you can listen for the <code>updateready</code> event to detect this and prompt the
user to reload the page:</p>
<p><pre>if (window.applicationCache) {
applicationCache.addEventListener('updateready', function() {
if (confirm('An update is available. Reload now?')) {
window.location.reload();
}
});
}</pre>
<p>For most applications, however, temporarily using the previous version of the code is probably acceptable.</p>
</div>
</li>
<li>
If any of the files mentioned in the <code>CACHE</code> section can't be retrieved, the entire cache will be disregarded.
<div class="details">
<p>All resources must successfully return. If any do not — returning a 404 or 500, for example — the entire cache will be ignored.</p>
<p>The next time the browser returns to your page, it will try to use the manifest again as if it was the first time it
encountered it.</p>
</div>
</li>
<li>If the manifest file itself can't be retrieved, the cache will ignored and all cached data associated with it will be disregarded.</li>
<li>Regardless of whether you include the address of the current page in the manifest, it will be cached.</li>
<li>In Chrome, you can see information about appcached sites by visiting <code>chrome://appcache-internals/</code>. This allows you to see which sites have appcached, when they were last modified, and how much space they're using. You can also remove appcaches here.</li>
<li>In Firefox, any resources served with <code>Cache-control: <strong>no-store</strong></code> will not be cached, even if they're explicitly included in the manifest.</li>
<li>Firefox will always ask the user for permission before caching a site for the first time.</li>
</ul>
</section>
<section id="sample">
<h2>Resources</h2>
<p>These resources have been invaluable while working with the appcache:</p>
<ul>
<li>AppCacheFacts Demo Site – <a href="./demo/">Demo</a></li>
<li>Open Web Camp IV presentation <a href="./peterlubbers-owc4/index.html">Building Offline Web Applications with AppCache</a> (2012)</li>
<li>Dive Into HTML5 – <a href="http://diveintohtml5.info/offline.html">Let's Take This Offline</a></li>
<li>Google Code Blog – <a href="http://googlecode.blogspot.com/2009/04/gmail-for-mobile-html5-series-using.html">Using AppCache to Launch Offline</a></a></li>
<li>HTML5 Rocks – <a href="http://www.html5rocks.com/tutorials/appcache/beginner/">A Beginner's Guide to Using the Application Cache</a></li>
<li>MDN Doc Center – <a href="https://developer.mozilla.org/en/offline_resources_in_firefox">Offline resources in Firefox</a></li>
<li>Safari Developer Library – <a href="http://developer.apple.com/library/safari/#documentation/appleapplications/reference/SafariWebContent/Client-SideStorage/Client-SideStorage.html">Storing Data on the Client</a></li>
<li>Online validator, JSON(P) validation API, and TextMate bundle) – <a href="http://manifest-validator.com">Cache Manifest Validator</a></li>
<li>A List Apart – <a href="http://www.alistapart.com/articles/application-cache-is-a-douchebag/">Application Cache is a Douchebag</a></li>
<li>Steve Souders' Browserscope test – <a href="http://www.stevesouders.com/blog/2012/09/10/clearing-browser-data/">Clearing Browser Data</a></li>
<li>The4thDimension – <a href="http://www.the4thdimension.net/2012/03/how-to-inhibit-caching-appcache.html">How to inhibit caching AppCache manifest?</a></li>
</ul>
</section>
<section id="footer">
<p>
© 2012 <a href="https://twitter.com/shinypb">Mark Christian</a>, <a href="https://twitter.com/ded">Dustin Diaz</a>, and <a href="https://twitter.com/peterlubbers">Peter Lubbers</a>. License: <a href="http://creativecommons.org/licenses/by/3.0/">CC Attribution 3.0</a>. Patches: <a href="https://github.com/shinyplasticbag/appcachefacts">GitHub</a>.
</p>
</section>
</body>
</html>