gears/sdk/tutorial.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">
   2
   3 <!--
   4 Copyright 2007, Google Inc.
   5
   6 Redistribution and use in source and binary forms, with or without
   7 modification, are permitted provided that the following conditions are met:
   8
   9  1. Redistributions of source code must retain the above copyright notice,
  10     this list of conditions and the following disclaimer.
  11  2. Redistributions in binary form must reproduce the above copyright notice,
  12     this list of conditions and the following disclaimer in the documentation
  13     and/or other materials provided with the distribution.
  14  3. Neither the name of Google Inc. nor the names of its contributors may be
  15     used to endorse or promote products derived from this software without
  16     specific prior written permission.
  17
  18 THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
  19 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  20 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
  21 EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  23 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  24 OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  25 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  26 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  27 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 -->
  29
  30 <html>
  31   <head>
  32     <title>Tutorial</title>
  33     <link rel="stylesheet" type="text/css" href="gears.css" />
  34   </head>
  35
  36 <body>
  37
  38 <h1>Tutorial</h1>
  39
  40 <div id="pagecontent">
  41
  42 <p>Any static HTML files, such as  documentation, can be enabled for viewing  offline by following these steps. This tutorial shows you how to create  a manifest file, and make your files  available  offline, using Gears. (Time estimate: 15 minutes.) </p>
  43 <h4>You will need:</h4>
  44 <ul>
  45   <li>Ability to edit basic JavaScript </li>
  46   <li>Ability to publish files to the HTTP server that hosts your files</li>
  47   <li>The static files that you want to enable for offline viewing</li>
  48   <li>For a list of supported browsers and platforms, see <a href="http://gears.google.com/">gears.google.com</a>.  </li>
  49 </ul>
  50 <h4>Files to download for this tutorial: </h4>
  51 <ul><li><a href="tutorials/tutorial_manifest.json">tutorial_manifest.json</a></li>
  52   <li><a href="tutorials/go_offline.html">go_offline.html</a></li>
  53   <li><a href="tutorials/go_offline.js">go_offline.js</a></li>
  54   <li><a href="resources/gears_init.js">gears_init.js</a></li>
  55 </ul>
  56 <h1>1. Edit the sample manifest file </h1>
  57 <h3>Save this <a href="tutorials/tutorial_manifest.json">tutorial manifest file</a> to your computer. </h3>
  58 <ul>
  59   <li>Rename it &quot;manifest.json&quot;. </li>
  60   <li>Open your <strong>manifest.json</strong> in an editor.</li>
  61 </ul>
  62 <h3>Edit the version value </h3>
  63 <p>The manifest file contains a series of attribute-value pairs. </p>
  64 <ul>
  65   <li> Replace <code>&quot;my_version_string&quot;</code> value with a version string that is meaningful to you. This value represents the version of your documents. Example: &quot;version 1.0&quot;. </li>
  66 </ul>
  67 <p>You will update this version string in the future to indicate that there is a change in any of your documents.</p>
  68 <h3>Edit the URLs </h3>
  69 <p>The &quot;entries&quot; attribute contains an array of URLs that you wish to capture and have available offline. </p>
  70 <ul>
  71   <li>For every file and image that you wish to capture, add a <code>&quot;url&quot;</code> entry into the <code>&quot;entries&quot;</code> array. Follow the format in the sample manifest file.</li>
  72   <li>Check that each entry except for the last one is followed by a comma. </li>
  73   <li>To have the tutorial's &quot;go_offline&quot; files available offline too, include them in the manifest. </li>
  74 </ul>
  75 <p>For example, if your documentation consists of an index.html page, a stylesheet style.css,  and a logo in the file resources/logo.gif in addition to the tutorial's files, you will have the following <code>&quot;url&quot;</code> entries:</p>
  76 <pre><code>&quot;entries&quot;: [
  77     { &quot;url&quot;: &quot;index.html&quot; },
  78     { &quot;url&quot;: &quot;style.css&quot; },
  79     { &quot;url&quot;: &quot;resources/logo.gif&quot; },
  80     { &quot;url&quot;: &quot;gears_init.js&quot;},
  81     { &quot;url&quot;: &quot;go_offline.html&quot;},
  82     { &quot;url&quot;: &quot;go_offline.js&quot;}
  83 ] </code></pre>
  84 <p><strong>Note</strong>: The    URLs can be fully-qualified, for example &quot;http://www.example.com/index.html&quot;, or they can be relative to the manifest file's location.</p>
  85 <h1>2. Add some User Interface </h1>
  86 <p>Some basic user interface is needed to provide a way for your user to request the offline functionality. </p>
  87 <h4>Download and save these  files to your computer:</h4>
  88 <p><a href="tutorials/go_offline.html">go_offline.html</a> - user interface sample <br />
  89   <a href="tutorials/go_offline.js">go_offline.js</a><br />
  90   <a href="resources/gears_init.js">gears_init.js</a> - provides access to Google Gears. </p>
  91 <p><strong><em>Special note:</em></strong> To keep this tutorial simple, the go_offline.html file is provided  to act as the user interface.</p>
  92 <p>You are not limited to using the provided file; you can  integrate the functionality provided in the go_offline.js JavaScript file into your application in other ways. </p>
  93 <p>Keep in mind that  the user will need to:</p>
  94 <ul>
  95   <li>Install Gears</li>
  96   <li>Allow your website to use Gears (a permissions dialog appears automatically) </li>
  97   <li>Enable the offline version of your documents </li>
  98 </ul>
  99 <h1>3. Upload files to your HTTP server </h1>
 100 <h4>Upload all the files and your documents to your HTTP server. </h4>
 101 <ul>
 102   <li>go_offline.html</li>
 103   <li>go_offline.js</li>
 104   <li>gears_init.js</li>
 105   <li>manifest.json</li>
 106   <li>All the files listed in your manifest.json file.</li>
 107 </ul>
 108 <p><strong>Important:</strong> Be sure all the files listed in the manifest file are available and accessible as listed. </p>
 109 <h1>4. Test: capture the files locally </h1>
 110 <p>In the testing steps, you act as the user. </p>
 111 <ul><li>If you haven't already, <a href="install.html">install Gears</a> on your computer. </li>
 112   <li>In your browser, type the URL of the go_offline.html page on your HTTP server
 113   </li>
 114   <ul>
 115     <li>For example: http://www.example.com/go_offline.html</li>
 116       </ul>
 117   <li>Click Capture. A status message  appears when the file capture is complete.</li>
 118   </ul>
 119 <h1>5. Test: access the captured files </h1>
 120 <ul>
 121   <li>Take your browser offline. Select File &gt; Work Offline. </li>
 122   <li>Clear your browser cache. In Firefox, select Tools &gt; Clear Private Data...,  check Cache, and click the &quot;Clear Private Data Now&quot; button. </li>
 123   <li>Type the URL of your document.
 124     <ul>
 125       <li>If the offline capture is in effect, you will see your stored document.</li>
 126       <li>If the offline capture is not in effect, you will see a browser error message</li>
 127       </ul>
 128   </li>
 129   </ul>
 130 <p>Clear your browser cache often while testing, to prevent seeing cached (but not necessarily offline-enabled) content. </p>
 131 <h3>Troubleshooting</h3>
 132 <ul>
 133   <li>Make sure you have installed Google Gears. </li>
 134   <li>All the URLs in the manifest file must be correct, and reachable from the directory that the manifest resides in. The manifest file and the URLs it references must be located in the same domain.  </li>
 135   <li>Check  that there aren't any typos or extraneous files listed in the manifest.</li>
 136   <li>The  code in <strong>go_offline.js</strong> expects that the manifest file is named &quot;manifest.json&quot; and that it resides in the same directory. Update the manifest.json references in go_offline.js as needed. </li>
 137   <li>Use a JavaScript debugger to see any errors that may be returned from the Gears API calls. </li>
 138   </ul>
 139 <h1>6. Publish it to your users</h1>
 140 <p>Your users can now access your documents offline by following the  instructions in Step 4 above.</p>
 141 <h1>7. Future changes: maintaining the manifest </h1>
 142 <p>Whenever you update the contents in the static HTML files, or if you add or remove  files, you must update the manifest file. When Google Gears detects a new manifest version string, the updated contents are automatically copied to your user's local machine when they next view any of your files. </p>
 143 <ul>
 144   <li>Always update the version string in the manifest file to indicate any changes. </li>
 145   <li>Update the manifest entries to correspond to any added or removed files.</li>
 146   <li>If you change just the content in the files, you need only to update the version string in the manifest file.</li>
 147 </ul>
 148 <p>&nbsp;</p>
 149 <p>&nbsp;</p>
 150 <p>For more information on the manifest file or the APIs used in this tutorial, see the <a href="api_localserver.html">LocalServer API Reference</a>. </p>
 151
 152
 153 </div>
 154 </body>
 155 </html>