Disable view source for Developer Tools.

[chromium-blink-merge.git] / chrome / common / extensions / docs / templates / articles / app_intents.html

<h1>Connect Apps with Web Intents</h1>

<p class="warning">
<b>Warning: </b>
Deprecated in Chrome 24.
Web intents are no longer supported.
</p>

<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>Chrome 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 class="warning">
<b>Warning: </b>
Deprecated in Chrome 24.
Web intents are no longer supported.
</p>

<p>
You must supply the intent in the manifest:
</p>

<pre data-filename="manifest.json">
"intents":{
 "http://webintents.org/edit" : [{
   "title" : "Best Image editing app",
   "type" : ["image/*"]
 }]
}
</pre>

<p>
Unlike extensions and hosted apps, Chrome applications do not 
need a "href" attribute in the manifest declaration, this is 
because Chrome Apps have a single entry point for 
launch - the <code>onLaunched</code> event.  
</p>

<h2 id="content">Handling content types</h2>

<p class="warning">
<b>Warning: </b>
Deprecated in Chrome 24.
Web intents are no longer supported.
</p>

<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 data-filename="manifest.json">
"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.app.runtime.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 class="warning">
<b>Warning: </b>
Deprecated in Chrome 24.
Web intents are no longer supported.
</p>

<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.app.runtime.onLaunched(function(intent) {
  // App Launched
  var data = intent.data;
});
</pre>

<h2 id="launching">Manipulating the file</h2>

<p class="warning">
<b>Warning: </b>
Deprecated in Chrome 24.
Web intents are no longer supported.
</p>

<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.app.runtime.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 blob = new Blob(['Lorem Ipsum'], {type: 'text/plain'});
      writer.write(blob);
    });
  }
});
</pre>

<h2 id="return">Returning data to calling application</h2>

<p class="warning">
<b>Warning: </b>
Deprecated in Chrome 24.
Web intents are no longer supported.
</p>

<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.app.runtime.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 class="warning">
<b>Warning: </b>
Deprecated in Chrome 24.
Web intents are no longer supported.
</p>

<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 data-filename="manifest.json">
"intents": {
 "http://webintents.org/edit" : [{
   "title" : "__MSG_intent_title__",
   "type" : ["image/*"],
   "disposition" : "inline"
 }]
}
</pre>

<h2 id="invoke">Invoking an action</h2>

<p class="warning">
<b>Warning: </b>
Deprecated in Chrome 24.
Web intents are no longer supported.
</p>

<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 class="warning">
<b>Warning: </b>
Deprecated in Chrome 24.
Web intents are no longer supported.
</p>

<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 id="client">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 id="service">Service</h3>
<pre>
chrome.app.runtime.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>