Documentation and sample for the experimental Clear API.

BUG=107518
TEST=

Review URL: https://chromiumcodereview.appspot.com/8932015

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@118446 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 95 insertions, 0 deletions

diff --git a/chrome/common/extensions/docs/static/experimental.clear.html b/chrome/common/extensions/docs/static/experimental.clear.html
new file mode 100644
index 0000000..3707fb0
--- /dev/null
+++ b/chrome/common/extensions/docs/static/experimental.clear.html
@@ -0,0 +1,95 @@
+<div id="pageData-name" class="pageData">Clear API</div>
+
+<!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+  Use the <code>chrome.experimental.clear</code> module to remove browsing data
+  from a user's local profile. This module is still experimental. For more
+  information regarding the usage of experimental APIs, see the
+  <a href="experimental.html">chrome.experimental.* APIs</a> page.
+</p>
+
+<h2 id="manifest">Manifest</h2>
+
+<p>
+  You must declare the "clear" permission in the
+  <a href="manifest.html">extension manifest</a> to use this API. As the API is
+  still experimental, you must declare the "experimental" permisson as well.
+</p>
+
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "clear",
+    "experimental"
+  ]</b>,
+  ...
+}</pre>
+
+<h2 id="usage">Usage</h2>
+
+<p>
+  This API provides a time-based mechanism for clearing a user's browsing data.
+  Your code should provide a timestamp which indicates the historical date after
+  which the user's browsing data should be removed. This timestamp is formatted
+  as the number of milliseconds since the Unix epoch (which can be retrieved
+  from a JavaScript <code>Date</code> object via the <code>getTime</code>
+  method).
+</p>
+
+<p>
+  For example, to clear all of a user's browsing data from the last week, you
+  might write code as follows:
+</p>
+
+<pre>var callback = function () {
+  // Do something clever here once data has been removed.
+};
+
+var millisecondsPerWeek = 1000 * 60 * 60 * 24 * 7;
+var oneWeekAgo = (new Date()).getTime() - millisecondsPerWeek;
+chrome.experimental.clear.browsingData(oneWeekAgo, {
+  "appcache": true,
+  "cache": true,
+  "cookies": true,
+  "downloads": true,
+  "fileSystems": true,
+  "formData": true,
+  "history": true,
+  "indexedDB": true,
+  "localStorage": true,
+  "pluginData": true,
+  "passwords": true,
+  "webSQL": true
+}, callback);</pre>
+
+<p>
+  The <code>chrome.experimental.clear.browsingData</code> method allows you to
+  remove various types of browsing data with a single call, and will be much
+  faster than calling multiple more specific methods. If, however, you only
+  want to clear one specific type of browsing data (cookies, for example), the
+  more granular methods offer a readable alternative to a call filled with JSON.
+</p>
+
+<pre>var callback = function () {
+  // Do something clever here once data has been removed.
+};
+
+var millisecondsPerWeek = 1000 * 60 * 60 * 24 * 7;
+var oneWeekAgo = (new Date()).getTime() - millisecondsPerWeek;
+chrome.experimental.clear.cookies(oneWeekAgo, callback);</pre>
+
+<p class="caution">
+  <strong>Important</strong>: Removing browsing data involves a good deal of
+  heavy lifting in the background, and can take <em>tens of seconds</em> to
+  complete, depending on a user's profile. You should use the callback mechanism
+  to keep your users up to date on the removal's status.
+</p>
+
+<h2 id="samples">Examples</h2>
+<p>
+  Samples for the <code>clear</code> API are available
+  <a href="http://code.google.com/chrome/extensions/trunk/samples.html#chrome.experimental.clear">on the samples page</a>.
+</p>
+
+<!-- END AUTHORED CONTENT -->