Document use of rs.js and widget in browser extension?

[phlummox]

I wondered if it would be worth documenting changes in code and/or usage that need to be made when using remotestorage.js and the connection widget from a browser extension. Not sure how many users of the library might be doing this, but in case it is of interest to others, I kept a few notes on what had to be done.

I used the 2.0.0-alpha.3 release. (I came across build and runtime errors when trying to use HEAD.)

I found there were a few changes that had to be made:

• Most browser extensions have specialised methods for starting an Oauth2 authentication flow. To launch a web flow, extension developers normally use something like launchWebAuthFlow (documented here for Google Chrome). But the widget code as it currently stands tries to launch a flow itself. As a result, the listeners added to buttons in the setClickHandlers() method of the widget need to be removed, and replaced with listeners that start the oauth flow in some browser-specific way. (In my case, I sent a message to another extension component, requesting it to kick off the authentication process.)

• Also in most browser extensions, there isn't a normal URL that can be used as a "redirect URL" for authorisation – instead, there'll be some browser-specific way of constructing the redirect URL such as this method for Google Chrome. (This isn't an rs.js-specific issue, of course, but I thought it might be worth mentioning.)

• Often, the RemoteStorage object will be in a different component of the extension from the widget. A widget API like the one proposed in New API for loading the widget #2 #970 would have been useful here, so that instead of calling on the RemoteStorage directly, the widget sends messages via some proxy object.

• Given that the extension will be handling the oauth process itself and getting an authentication token back, remoteStorage.connect can't be called in the usual way. I read the documentation here on calling remoteStorage.connect with a supplied token, but noted that it doesn't work if the user wants to use Google Drive as a backend.

  Instead, the method that needs to be called in that case is remoteStorage.googledrive.configure(settings), like so:

  remoteStorage.googledrive.configure( { token: "<SOME_AUTH_TOKEN>" } );
  

Anyway. Hopefully these notes might be of use to anyone attempting something similar. If you think it would be worth incorporating some or all of this into the documentation, let me know and perhaps I can put a PR together.