Extensions Docs Server: First doc conversions

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

+<!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+Use the <code>chrome.fileBrowserHandler</code> module to
+extend the Chrome OS file browser.
+For example, you can use this API
+to enable users to upload files to your website.
+</p>
+<p class="caution">
+<b>Important:</b>
+This API works <b>only on Chrome OS</b>.
+</p>
+<p>
+The Chrome OS file browser comes up when
+the user either presses Ctrl+M
+or connects an external storage device,
+such as an SD card, USB key, external drive, or digital camera.
+Besides showing the files on external devices,
+the file browser can also display files
+that the user has previously saved to the system.
+</p>
+<p>
+When the user selects one or more files,
+the file browser adds buttons
+representing the valid handlers for those files.
+For example, in the following screenshot,
+selecting a file with a ".jpg" suffix
+results in an "Upload to Picasa" button that the user can click.
+</p>
+<p>
+<img src="/static/images/filebrowserhandler.png"
+  width="640" height="400" alt="file browser screenshot" />
+</p>
+<h2 id="manifest">Manifest</h2>
+<p>
+You must declare the "fileBrowserHandler" permission
+in the <a href="manifest.html">extension manifest</a>,
+and you must use the "file_browser_handlers" field
+to register the extension as a handler of at least one file type.
+You should also provide a 16x16 icon
+to be displayed on the button.
+For example:
+</p>
+<pre>
+{
+  "name": "My extension",
+  ...
+  <b>"file_browser_handlers"</b>: [
+    {
+      <b>"id"</b>: "upload",
+      <b>"default_title"</b>: "Save to Gallery", <em>// What the button will display</em>
+      <b>"file_filters"</b>: [
+        "filesystem:*.jpg", <em>// To match all files, use "filesystem:*.*"</em>
+        "filesystem:*.jpeg",
+        "filesystem:*.png"
+      ]
+    }
+  ]</b>,
+  "permissions" : [
+    <b>"fileBrowserHandler"</b>
+  ],
+  "icons": { <b>"16"</b>: "icon16.png",
+             "48": "icon48.png",
+            "128": "icon128.png" },
+  ...
+}</pre>
+<p class="note">
+<b>Note:</b>
+You can specify locale-specific strings for the value of "default_title".
+See <a href="i18n.html">Internationalization (i18n)</a> for details.
+</p>
+<h2 id="code">Implementing a file browser handler</h2>
+<p>
+To use this API,
+you must implement a function that handles the <code>onExecute</code> event
+of <code>chrome.fileBrowserHandler</code>.
+Your function will be called whenever the user clicks the button
+that represents your file browser handler.
+In your function, use the HTML5
+<a href="http://www.html5rocks.com/tutorials/file/filesystem/">FileSystem API</a>
+to get access to the file contents.
+Here is an example:
+</p>
+<pre>
+<em>//In background.html:</em>
+chrome.fileBrowserHandler.onExecute.addListener(function(id, details) {
+  if (id == 'upload') {
+    var fileEntries = details.entries;
+    for (var i = 0, entry; entry = fileEntries[i]; ++i) {
+      entry.file(function(file) {
+        <em>// send file somewhere</em>
+      });
+    }
+  }
+});
+</pre>
+<p>
+Your event handler is passed two arguments:
+</p>
+<dl>
+  <dt> id </dt>
+  <dd> The "id" value from the manifest file.
+       If your extension implements multiple handlers,
+       you can check the <code>id</code> value
+       to see which handler has been triggered.
+       </dd>
+  <dt> details </dt>
+  <dd> An object describing the event.
+       You can get the file or files that the user has selected
+       from the <code>entries</code> field of this object,
+       which is an array of
+       FileSystem <code>Entry</code> objects.
+       </dd>
+</p>
+<!--
+<h2 id="manifest_details">Manifest details</h2>
+<p class="authornote">
+{PENDING: give details about "id" and "default_title".
+It should be unique within your extension -- don't worry about other extensions.
+"default_title" implies that you can change the title,
+but you can't aside from internationalizing it.
+</p>
+<p class="authornote">
+{PENDING: give details about the file_filters entry.
+File filters are currently case-sensitive, but we plan to change that.
+Mention <code>filesystem:*.*</code>.
+</p>
+-->
+<!--
+<h2 id="examples">Examples</h2>
+<p>
+For examples of using this API, see ...
+For other examples and for help in viewing the source code, see
+<a href="samples.html">Samples</a>.
+</p>
+-->
+<!-- END AUTHORED CONTENT -->