Add chrome.webstore API methods to allow sites to see progress of installation

chrome/renderer/resources/extensions/webstore_custom_bindings.js

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Custom binding for the webstore API.
 
 var webstoreNatives = requireNative('webstore');
+var Event = require('event_bindings').Event;
 
 function Installer() {
   this._pendingInstall = null;
+  this.onInstallStageChanged =
+      new Event(null, [{name: 'stage', type: 'string'}], {unmanaged: true});
+  this.onDownloadProgress =
+      new Event(null, [{name: 'progress', type: 'number'}], {unmanaged: true});

[asargent_no_longer_on_chrome, 2014/03/03 18:49:08]

We'll want to update the documentation for this at 

https://developers.google.com/chrome/web-store/docs/inline_installation

which doesn't seem to use autogeneration based on the webstore.json file, and
for instance doesn't mention the already existing url and onSuccess/onFailure
arguments. 


BTW, did you already think about the API alternative of having these be passed
in as arguments to the install function like the onSuccess/onFailure callbacks?
I don't know if that would be better, but I guess there is some asymmetry in
doing it this way. 

[Devlin, 2014/03/03 21:15:13]

We discussed it, but we thought that would be too many methods shoved in
(especially when so many are optional, and you might want a subset of them), and
that would also prevent us from using the Event structure (which Ben has been a
proponent of using).

[asargent_no_longer_on_chrome, 2014/03/03 22:25:33]

Ok, sgtm. 

 }
 
 Installer.prototype.install = function(url, onSuccess, onFailure) {
   if (this._pendingInstall)
     throw 'A Chrome Web Store installation is already pending.';

[not at google - send to devlin, 2014/03/01 01:42:07]

throw new Error(...)

same for all the rest.

[Devlin, 2014/03/03 17:44:59]

Done.

[asargent_no_longer_on_chrome, 2014/03/03 18:49:08]

If developers find themselves in a situation where there is a pending but
seemingly stuck install (eg no download progress for a while), would it make
sense to try and provide a cancel function? 

I guess the best they could do today is to either automatically reload the page,
or ask the user to do it manually?

[Devlin, 2014/03/03 21:15:13]

That's a good idea, but I think it's a separate issue (probably with its own API
doc and all), if that's okay.

That being said, Ben, initial thoughts?

[asargent_no_longer_on_chrome, 2014/03/03 22:25:33]

Maybe just log a bug for follow-up and we can have a discussion there. 

[Devlin, 2014/03/03 22:49:16]

Done. crbug.com/348752

-  var installId = webstoreNatives.Install(url, onSuccess, onFailure);
+  if (url !== undefined && typeof(url) !== 'string')
+    throw 'The Chrome Web Store item link URL parameter must be a string.';
+  if (onSuccess !== undefined && typeof(onSuccess) !== 'function')
+    throw 'The success callback parameter must be a function.';
+  if (onFailure !== undefined && typeof(onFailure) !== 'function')
+    throw 'The failure callback parameter must be a function.';
+
+  var installId = webstoreNatives.Install(
+      this.onInstallStageChanged.hasListeners(),
+      this.onDownloadProgress.hasListeners(),

[not at google - send to devlin, 2014/03/01 01:42:07]

make sure you document that listeners need to be added before install() is
called.

[Devlin, 2014/03/03 17:44:59]

Doc'd here in a comment and in the Event description in the .json.

+      url,
+      onSuccess,
+      onFailure);
   if (installId !== undefined) {
     this._pendingInstall = {
       installId: installId,
       onSuccess: onSuccess,
       onFailure: onFailure
     };
   }
 };
 
 Installer.prototype.onInstallResponse = function(installId, success, error) {
   var pendingInstall = this._pendingInstall;
   if (!pendingInstall || pendingInstall.installId != installId) {
     // TODO(kalman): should this be an error?
     return;
   }
 
   try {
     if (success && pendingInstall.onSuccess)
       pendingInstall.onSuccess();
     else if (!success && pendingInstall.onFailure)
       pendingInstall.onFailure(error);
   } catch (e) {
     console.error('Exception in chrome.webstore.install response handler: ' +
                   e.stack);
   } finally {
     this._pendingInstall = null;
   }
 };
 
+Installer.prototype.onInstallStageChanged = function(installStage) {
+  this.onInstallStageChanged.dispatch(installStage);
+};
+
+Installer.prototype.onDownloadProgress = function(progress) {
+  this.onDownloadProgress.dispatch(progress);
+};
+
 var installer = new Installer();
 
 var chromeWebstore = {
-  install: function install(url, onSuccess, onFailure) {
+  install: function (url, onSuccess, onFailure) {
     installer.install(url, onSuccess, onFailure);
-  }
+  },
+  onInstallStageChanged: installer.onInstallStageChanged,
+  onDownloadProgress: installer.onDownloadProgress
 };
 
-// Called by webstore_binding.cc.
-function onInstallResponse(installId, success, error) {
-  installer.onInstallResponse(installId, success, error);
-}
-
-// These must match the names in InstallWebstorebinding in
+// This must match the name in InstallWebstoreBindings in
 // chrome/renderer/extensions/dispatcher.cc.
 exports.chromeWebstore = chromeWebstore;
-exports.onInstallResponse = onInstallResponse;
+
+// Called by webstore_binding.cc.

[asargent_no_longer_on_chrome, 2014/03/03 18:49:08]

nit: I assume you meant webstore_bindings.cc ?

[Devlin, 2014/03/03 21:15:13]

Whoops, done.

+exports.onInstallResponse =
+    Installer.prototype.onInstallResponse.bind(installer);
+exports.onInstallStageChanged =
+    Installer.prototype.onInstallStageChanged.bind(installer);
+exports.onDownloadProgress =
+    Installer.prototype.onDownloadProgress.bind(installer);