Extensions Docs Server: Doc conversion script

chrome/common/extensions/docs/server2/templates/articles/app_intents.html

+<h1 class="page_title">Connect Apps with Web Intents</h1>
+<p>
+<a href="http://webintents.org/">Web Intents</a>
+allow your application to quickly communicate
+with other applications on the user's system and inside their browser.
+Your application can register to handle specific user actions
+such as editing images via the <code>manifest.json</code>;
+your application can also invoke actions to be handled by other applications.
+</p>
+<p>Pacakged apps use Web Intents as their primary mechanism for inter-app 
+communication.</p>
+<p class="note">
+<b>API Samples: </b>
+Want to play with the code?
+Check out the
+<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/webintents">webintents</a> sample.
+</p>
+<h2 id="register">Register your app to handle an action</h2>
+<p>
+You must supply the intent in the manifest:
+</p>
+<pre>
+"intents":{
+ "http://webintents.org/edit" : [{
+   "title" : "Best Image editing app",
+   "type" : ["image/*"]
+ }]
+}
+</pre>
+<p>
+Unlike extensions and hosted apps, packaged applications do not 
+need a "href" attribute in the manifest declaration, this is 
+because packaged apps have a single entry point for 
+launch - the <code>onLaunched</code> event.  
+</p>
+<h2 id="content">Handling content types</h2>
+<p>
+Your application can be the user's preferred choice for handling a file type.
+For example, your application could handle viewing images or viewing pdfs.
+You must supply the intent in the manifest
+and use the "http://webintents.org/view" action:
+</p>
+<p>To be able declare your application's ability to view RSS and ATOM 
+feeds, you would add the following to your manifest.
+</p>
+<pre>
+"intents": {
+ "http://webintents.org/view" : [{
+   "title" : "RSS Feed Reader",
+   "type" : ["application/atom+xml", "application/rss+xml"]
+ }]
+}
+</pre>
+<p>
+Your application will receive intent payload through the <code>onLaunched</code> event.
+</p>
+<pre>
+chrome.experimental.app.onLaunched(function(intent) {
+  // App Launched
+  if(intent.action == "http://webinents.org/view" &amp;&amp;
+     intent.type == "application/atom+xml") {
+    // obtain the ATOM feed data.
+    var data = intent.data;
+  }
+});
+</pre>
+<h2 id="launching">Launching an app with a file</h2>
+<p>
+If your app handles the <code>view</code> intent,
+it is possible to launch it from the command line with a file as a parameter.
+</p>
+<pre>
+chrome.exe --app-id [app_id] [path_to_file]
+</pre>
+<p>
+This will implicity launch your application with an intent payload populated
+with the action set to "http://webintents.org/view", the type set to the 
+mime-type of the file and the data as a <code>FileEntry</code> object.
+</p>
+<pre>
+chrome.experimental.app.onLaunched(function(intent) {
+  // App Launched
+  var data = intent.data;
+});
+</pre>
+<h2 id="launching">Manipulating the file</h2>
+<p>
+  When your application is launched with a file as the parameter
+  on the command-line,
+  the <code>intent.data</code> property is a <code>FileEntry</code>.
+  This is really cool because now you have a direct reference back to the physical
+  file on the disk,
+  and you can write data back to it.
+</p>
+<pre>
+chrome.experimental.app.onLaunched(function(intent) {
+  // App Launched
+  var data = intent.data;
+  if(data instanceof FileEntry) {
+    data.createWriter(function(writer) {
+      writer.onwriteend = function(e) {
+        console.log('Write completed.');
+      };
+      writer.onerror = function(e) {
+        console.log('Write failed: ' + e.toString());
+      };
+      // Create a new Blob and write it to log.txt.
+      var bb = new BlobBuilder(); // Note: window.WebKitBlobBuilder in Chrome 12.
+      bb.append('Lorem Ipsum');
+      writer.write(bb.getBlob('text/plain'));
+    });
+  }
+});
+</pre>
+<h2 id="return">Returning data to calling application</h2>
+<p>
+Lots of applications want to cooperate
+with the app that invoked them.
+It's easy to send data back to the calling client
+using <code>intent.postResult</code>:
+</p>
+<pre>
+chrome.experimental.app.onLaunched(function(intent) {
+  // App Launched
+  console.log(intent.action);
+  console.log(intent.type);
+  var data = intent.data;
+  // Do something with the data;
+  intent.postResult(newData);
+});
+</pre>
+<h2 id="localize">Localizing your app title</h2>
+<p>
+If your application or extension is localized
+as per the guidelines in
+<a href="i18n.html">Internationalization (i18n)</a>,
+you can localize the title of your intent in the picker
+using the exact same infrastructure:
+</p>
+<pre>
+"intents": {
+ "http://webintents.org/edit" : [{
+   "title" : "__MSG_intent_title__",
+   "type" : ["image/*"],
+   "disposition" : "inline"
+ }]
+}
+</pre>
+<h2 id="invoke">Invoking an action</h2>
+<p>
+If your application needs to be able
+to use the functionality of another application,
+it can simply ask the browser for it.
+To ask for an application that supports image editing,
+it's as simple as:
+</p>
+<pre>
+var intent = new WebKitIntent("http://webintents.org/edit", "image/png", "dataUri://");
+window.navigator.webkitStartActivity(intent, function(data) {
+// The data from the remote application is returned here.
+});
+</pre>
+<h2 id="errors">Handling Errors and Exceptions</h2>
+<p>
+   If your service application needs to signal to the client application
+   that an unrecoverable error has occurred,
+   then your application will need
+   to call <code>postError</code> on the intent object.
+   This will signal to the client’s onError callback
+   that something has gone wrong.
+</p>
+<h3>Client</h3>
+<pre>
+var intent = new WebKitIntent("http://webintents.org/edit", "image/png", "dataUri://");
+var onSuccess = function(data) {};
+var onError = function() {};
+window.navigator.webkitStartActivity(intent, onSuccess, onError);
+</pre>
+<h3>Service</h3>
+<pre>
+chrome.experimental.app.onLaunched(function(intent) {
+  // App Launched
+  console.log(intent.action);
+  console.log(intent.type);
+  var data = intent.data;
+  // Do something with the data;
+  intent.postResult(newData);
+});
+</pre>
+<p class="backtotop"><a href="#top">Back to top</a></p>