Extensions Docs Server: First doc conversions

chrome/common/extensions/docs/server2/templates/private/storage_intro.html

+<!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+Use the <code>chrome.storage</code> module
+to store, retrieve, and track changes to user data.
+This API has been optimized
+to meet the specific storage needs of extensions.
+It provides the same storage capabilities as the
+<a href="https://developer.mozilla.org/en/DOM/Storage#localStorage">localStorage API</a>
+with the following key differences:
+</p>
+<ul>
+  <li>User data can be automatically synced with Chrome sync
+  (using <code>storage.sync</code>).</li>
+  <li>Your extension's content scripts can directly access user data
+  without the need for a background page.</li>
+  <li>A user's extension settings can be persisted
+  even when using
+  <a href="manifest.html#incognito">split incognito behavior</a>.</li>
+  <li>User data can be stored as objects
+  (the <code>localStorage API</code> stores data in strings).</li>
+</ul>
+<h2 id="manifest">Manifest</h2>
+<p>You must declare the "storage" permission in the <a
+  href="manifest.html">extension manifest</a>
+  to use the storage API.
+  For example:</p>
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "storage"
+  ]</b>,
+  ...
+}</pre>
+<h2 id="using-sync">Usage</h2>
+<p>
+To store user data for your extension,
+you can use either
+<code>storage.sync</code> or
+<code>storage.local</code>.
+When using <code>storage.sync</code>,
+the stored data will automatically be synced
+to any Chrome browser that the user is logged into,
+provided the user has sync enabled.
+</p>
+<p>
+When Chrome is offline,
+Chrome stores the data locally.
+The next time the browser is online,
+Chrome syncs the data.
+Even if a user disables syncing,
+<code>storage.sync</code> will still work.
+In this case, it will behave identically
+to <code>storage.local</code>.
+</p>
+<p class="warning">
+Confidential user information should not be stored!
+The storage area isn't encrypted.
+</p>
+<h2 id="limits">Storage and throttling limits</h2>
+<p><code>chrome.storage</code> is not a big truck.
+It's a series of tubes.
+And if you don't understand,
+those tubes can be filled,
+and if they are filled
+when you put your message in,
+it gets in line,
+and it's going to be delayed
+by anyone that puts into that tube
+enormous amounts of material.
+<p>For details on the current limits
+of the storage API, and what happens
+when those limits are exceeded, please
+see the <a href="#apiReference">API reference</a>.
+<h2 id="examples">Examples</h2>
+<p>
+The following example checks for
+CSS code saved by a user on a form,
+and if found,
+stores it.
+</p>
+<pre>
+function saveChanges() {
+  // Get a value saved in a form.
+  var theValue = textarea.value;
+  // Check that there's some code there.
+  if (!theValue) {
+    message('Error: No value specified');
+    return;
+  }
+  // Save it using the Chrome extension storage API.
+  chrome.storage.sync.set({'value': theValue}, function() {
+    // Notify that we saved.
+    message('Settings saved');
+  });
+}
+</pre>
+<p>
+If you're interested in tracking changes made
+to a data object,
+you can add a listener
+to its <code>onChanged</code> event.
+Whenever anything changes in storage,
+that event fires.
+Here's sample code
+to listen for saved changes:
+</p>
+<pre>
+chrome.storage.onChanged.addListener(function(changes, namespace) {
+  for (key in changes) {
+    var storageChange = changes[key];
+    console.log('Storage key "%s" in namespace "%s" changed. ' +
+                'Old value was "%s", new value is "%s".',
+                key,
+                namespace,
+                storageChange.oldValue,
+                storageChange.newValue);
+  }
+});
+</pre>
+<p>
+You can find examples that use this API on the
+<a href="samples.html#sty">Samples page</a>.
+</p>
+<!-- END AUTHORED CONTENT -->