Upcoming changes to the Jetpack Widget API

Between bug 612169 and bug 569479, the widget API has undergone a major transformation in the upcoming 0.10 SDK release.

Both sets of changes have made the API more compact, reducing the amount of code required to build widgets. The Electrolysis (e10s) changes are in preparation for moving Jetpack code out of the main Firefox process. They also make the widget API significantly more powerful, combining the current widget functionality with content scripts.

The e10s changes have affected the API to a significant degree; your widgets will certainly require more than just cosmetic changes.  I was worried at first that the e10s changes would complicate things, causing more verbose code patterns, and tricky message sequences to wire things together. However, the opposite was true: The documentation examples and the automated test code were both *more compact* and *simpler* after I’d rewritten them to use the new API.

Here’s an example widget that shows the Facebook profile pic of the most recent friend in your news feed:

require("widget").Widget({
  label: "Latest Friend",
  contentURL: "https://www.facebook.com/home.php",
  contentScript: "document.location = document.querySelector('.profilePic').src;",
  contentScriptWhen: "ready",
  onClick: function() require("tabs").tabs.active.location = this.contentURL
});

Hmmm, with the page-worker module, querySelectorAll and some hot timer action, you could have a Rockmelt-y bar…

A summary of the API changes:

  • You no longer need to explicitly add and remove widgets.
  • Constructing a widget immediately adds it to the add-on bar. To remove a widget, call its destroy() method.
  • The image property has been removed. Instead use the contentURL property, which can be used with image URLs, or local or remote content URLs. The content property is still present, used for HTML fragments or plain text.
  • The API now exposes the page-mod API set – meaning that you can attach a content script either inline via contentScript, or a separate file via contentScriptURL, and specify whether it runs at load or when the DOM is ready via contentScriptWhen.
  • The onLoad and onReady event listeners have been removed in favor of content scripts, where you can listen for those events, and post messages back to your Jetpack code. The examples in the docs show how easy this is.

For more details, check out the updated widget API documentation.

About these ads

3 Comments on “Upcoming changes to the Jetpack Widget API”

  1. Paul Everitt says:

    I’m trying this with yesterday’s tip.tar.gz download of the SDK. I’m trying to get a status bar icon with an image that is stored in my package.

    What is the URL scheme one should use for local content? I’ve tried various approaches with no luck.

    Also, it seems the examples (reddit and reading-data) are out of date. Which is a shame, because they would both answer most of my questions.

    • The examples have been updated.

      The URL scheme for local content is via the ‘self’ module. If you have file ‘myfile.html’ in your package’s ‘data’ directory, your widget would look like this:

      widgets.Widget({
      label: ‘my widget’,
      contentURL: require(‘self’).data.url(‘myfile.html’)
      });


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.