mitcho.com » Jetpack

Beginning development with Jetpack SDK 0.2

mitcho — Wed, 14 Apr 2010 16:20:47 +0000

This article is a translation of a recent article in Japanese by fellow Jetpack Ambassador Gomita which was published on the Mozilla Labs Jetpack blog. I’m cross-posting it here for posterity.

Mozilla Labs recently released version 0.2 of the Jetpack SDK, which fixes some issues of the 0.1 release such as a glitch regarding development with Windows. SDK 0.2 doesn’t include the planned APIs for rapid development of new browser functionality, but you can still play with SDK 0.2 to get a flavor for development with the Jetpack SDK.

In this article we begin by setting up an SDK 0.2 development environment and explain the steps required to develop a simple, practical add-on using SDK 0.2. The instructions here are for Windows, but the basic steps are the same in every platform.

Installing Python

The first step to using the Jetpack SDK is to install Python. How to install Python depends on your OS, but in Windows you can choose the “Python 2.6.5 Windows installer” from the Python site and follow the installation wizard. Here, I’ll use C:\Python26\ as the installation path.

After the install, you can activate the python command in your command line by adding C:\Python26 to the Windows Path preference. (If there is already another value, delimit with a semicolon: “;”.) Run the command “cmd” from the Start menu to start the command prompt and run python -V to confirm the Python version, Python 2.6.2:

C:\>python -V
Python 2.6.2

Note, the Jetpack SDK Docs state that Python 2.5+ is required, but there seem to be some incompatibilities with Python 3.0.1 at this time. In addition, in my experience the SDK worked fine without the “Python for Windows extensions.”

Setting up the Jetpack SDK

Next, we set up the Jetpack SDK. Download the Jetpack SDK 0.2 package from the Jetpack site, unzip it, and place it somewhere convenient. Here, I used C:\jetpack-sdk-0.2.

To use the Jetpack SDK, it must be “activated.” From the command prompt, go to the Jetpack SDK folder and run bin\activate:

C:\jetpack-sdk-0.2>bin\activate
Welcome to the Jetpack SDK. Run 'cfx docs' for assistance.
(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2>

Next, run cfx docs to open the SDK documentation in the browser. The SDK documentation starts a local server on port 8888.

(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2>cfx docs
One moment.
Opening web browser to http://127.0.0.1:8888.

The package directory structure

Addons built with the Jetpack SDK are called “packages.” Let’s try building a simple “hello world”-style package, but first let’s see what the final directory structure of this package will look like:

directory/file	Note
jetpack-sdk-0.2	the Jetpack SDK folder
packages	the main packages folder
hello-world	package root
package.json	package manifest file
README.md	package documentation
lib	the package code directory
main.js	main program code
simple-dialog.js	a custom code library

The package’s root directory is placed in the “packages” directory in the Jetpack SDK folder, and includes the package.json manifest file and the README.md documentation file. The lib folder includes the package’s main program code and any custom libraries used by our addon.

Creating the package

We begin by creating the hello-world directory in C:\jetpack-sdk-0.2\packages . Next the manifest file package.json is created. The manifest file includes metadata about our package in JSON format. If you’ve ever created a XUL-style addon before, you can think of this as similar to the install.rdf file. Here, I used the following as the manifest:

{
    "id": "helloworld@xuldev.org",
    "version": "0.1",
    "description": "This is my first package.",
    "author": "Gomita "
}

The id property is used as a unique ID for all addons including Jetpack packages and is often formatted as an email address. This corresponds to XUL-based addons’ <em:id> tag.

Next, reload the SDK documentation in the browser and confirm that “hello-world” shows up under “Package Reference.”

Writing the main code

The next step is to add some working code to the hello-world package. Create a lib folder under the package root and create a main.js under lib with the following code:

exports.main = function(options, callbacks) {
    console.log("Hello, World!");
};

The main program code is always loaded as a module called main. This main property is made accessible from outside code using the CommonJS-style code exports.main = .... console.log is a global function made available by Jetpack and the SDK prints the string to the command prompt.

It’s worth noting that, in the current Jetpack SDK, calling “console.log("こんにちは");” doesn’t yield the expected Japanese output. In the future such output will be handled through the planned localization API.

Testing our package

With some simple code in our main function, it’s time to try this code out. To test this code, we run cfx run -a firefox in the command prompt. By running cfx run with the -a firefox option, we load our package into a brand new Firefox profile and launch Firefox.

(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2>cd packages\hello-world

(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2\packages\hello-world>cfx run -a firefox
info: Hello, World!
OK
Total time: 1.531000 seconds
Program terminated unsuccessfully.

After Firefox loads, confirm that the command prompt reads info: Hello, World! When you quit Firefox, the testing will end.

Using a standard library

Now we’ll edit our code to invoke the timer library which is one of the Jetpack SDK’s standard libraries. The timer library is a module which abstracts various timer-related functionality, similar to the DOM’s window.setTimeout, window.clearTimeout. Details on this library are available in the SDK documentation. Moreover, although not in the documentation, timer.setInterval and timer.clearInterval also work in this version.

To use this library in our main program code, we first must invoke this library with the CommonJS require function. We modify the main.js file as follows:

var timer = require("timer");
exports.main = function(options, callbacks) {
    timer.setInterval(function() {
        console.log(new Date().toLocaleTimeString());
    }, 1000);
};

After this change, run cfx run -a firefox in the command prompt to test it. Check to make sure that the current time is being printed to the command prompt once a second:

(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2\packages\hello-world>cfx run -a firefox
info: 10:37:21
info: 10:37:22
info: 10:37:23
info: 10:37:24
info: 10:37:25

Creating a custom library

Next we’ll create a custom library to add some functionality not currently included in the Jetpack standard library. Implementing advanced functionality in add-ons, like filesystem access, involves using XPCOM components. Jetpack encourages seprarating the use of XPCOM components into separate modules which are then used by the main program code. The Jetpack SDK doesn’t currently disallow direct XPCOM access within Jetpack add-on code, but such a restriction is forthcoming. Modularizing XPCOM code into separate libraries now allow you to easily migrate to equivalent standard libraries in the future.

Let’s create a simple-dialog library to display a modal dialog much like window.alert does. The Jetpack code’s runtime environment doesn’t include access to the regular window or document objects, so just calling window.alert doesn’t work. To create an alert from this context, we use the nsIPromptService XPCOM component. In our package’s lib folder, create a simple-dialog.js file. Just like our main program code, we implement this library as a CommonJS module using exports.methodname = function(...){...}.

The simple-dialog library will have these two methods:

Method	Note
`alert(text)`	Displays an alert dialog with the string in text and an OK button. Equivalent to the DOM’s `window.alert`.
`confirmYesNo(text)`	Displays a confirmation dialog with the string in text and Yes and No buttons. The method returns `true` if the user presses “yes” and `false` if “no.”

Here is the code for simple-dialog.js:

var promptSvc = Cc["@mozilla.org/embedcomp/prompt-service;1"].
                getService(Ci.nsIPromptService);

exports.alert = function(text) {
    promptSvc.alert(null, "[Jetpack]", text);
};

exports.confirmYesNo = function(text) {
    var pos = promptSvc.confirmEx(
        null, "[Jetpack]", text, promptSvc.STD_YES_NO_BUTTONS,
        null, null, null, null, {}
    );
    return pos == 0;
};

Lines 1-2 are for calling nsIPromptService. Note that Cc, Ci are aliases for Components.classes and Components.interfaces, respectively, and are made available by Jetpack as global variables. Lines 4-6 implement the alert method for showing alert dialogs using nsIPromptService’s alert method. Lines 8-14 implement simple-dialog’s confirmYesNo method using nsIPromptService’s confirmEx method to display the dialog with yes and no buttons. nsIPromptservice’s confirmEx method returns 0 if the user presses “yes” and 1 if “no”, so we modify this value and return it.

Using our custom library

Let’s call this new custom library from our main program code and verify that it works. Here’s our updated main.js file:

var simpleDialog = require("simple-dialog");

exports.main = function(options, callbacks) {
    var adult = simpleDialog.confirmYesNo("Are you over 18 years old?");
    if (adult) {
        simpleDialog.alert("Welcome!");
    }
    else {
        simpleDialog.alert("Good bye!");
    }
};

Run cfx run -a firefox and confirm that a confirmation dialog, as seen below, is displayed. Pressing “yes” and “no” should give you the appropriate alert dialogs as well.

Implementing a network status observer

Now let’s use this hello-world package as a foundation for a more practical add-on. Using the observer-service module included with the Jetpack SDK, we can monitor Firefox’s online/offline network status changes.

Firefox internally broadcasts various application events to observers via the nsIObserverService XPCOM component. When Firefox goes offline, a network:offline-status-changed notification is broadcast. To subscribe this notification and act on it, we use the observer-service library’s add method. add’s first argument is the name of the notification we want to subscribe to and the second argument is a callback function. The callback function is given two arguments, of which the second is a string equal to either “online” or “offline.” In our add-on, we’ll check this value and display an appropriate alert using simple-dialog.

var simpleDialog = require("simple-dialog");
var observer = require("observer-service");

exports.main = function(options, callbacks) {
    observer.add("network:offline-status-changed", function(sbj, data) {
        if (data == "online") {
            simpleDialog.alert("Firefox is now online.");
        }
        else if (data == "offline") {
            simpleDialog.alert("Firefox is now offline.");
        }
    });
};

Launch Firefox by running cfx run -a firefox and then choose “File” > “Work Offline” and you should get a notification:

Adding documentation

If you add documentation to a package, you can view it by clicking that package in the SDK Documentation. To add documentation, create a README.md file in the package root directory. README.md is written in Markdown format which looks like this:

This is my *first* package.
* foo
* bar
* baz

Now if you load the SDK documentation using cfx docs and click on the “hello-world” link, you’ll see this documentation together with the package metadata.

Exporting an install package

Jetpack add-ons which are created in this way can then be exported into Firefox-standard XPI files. To export an XPI, go to the package’s root directory in the command prompt and run cfx xpi.

(C:\jetpack-sdk-0.2) C:\jetpack-sdk-0.2\packages\hello-world>cfx xpi
Exporting extension to hello-world.xpi.

This creates an XPI file called hello-world.xpi. Opening this file in any Firefox profile will let you install it using the regular add-on install mechanism.

Related posts brought to you by Yet Another Related Posts Plugin.

Spring is for Speaking: JSConf, WordCamp SF, IACL

mitcho — Sat, 20 Mar 2010 04:37:04 +0000

I recently confirmed three different very exciting speaking gigs which I’ll be doing this spring:

JSConf.us:

I’ll be putting my Mozilla Jetpack Ambassador hat on to represent Mozilla Labs’ Jetpack project at the premier Javascript conference in North America, JSConf.us, which this year will be April 17-18 in Washington D.C. and has a pirate theme.¹ I’ll be giving a short talk in the main session and will also lead a hands-on Jetpack workshop in the hacker lounge. I’ve heard that JSConf is a lot of fun and I’m really looking forward to it!

WordCamp San Francisco:

I’m honored to have been invited to give a talk at WordCamp San Francisco 2010. WordCamps are community-organized events for the WordPress community, and the San Francisco WordCamp is the original and biggest. WordCamp SF will be at the Mission Bay Conference Center on May 1st. Tickets available.

My talk is tentatively titled “Abstract Your Code.”² WordPress is a great platform to build amazing content-rich applications on, and many of us have written new functionality in the form of plugins. I hope to encourage developers to make their code more portable and reusable after the project is done—or, ideally, to even start with abstraction in mind—to add to the “life” of the code and to consider then open-sourcing that functionality.

Hope to see you there!

International Association of Chinese Linguistics (IACL) 18:

Finally, I’m thrilled to say that I got a paper accepted to the annual meeting of the International Association of Chinese Linguistics which this year is at Harvard on May 20-22. IACL is the big conference for Chinese linguistics, with about 180 papers presenting. I’ll be presenting Two Onlys in Mandarin Chinese, my recent work on the formal syntax/semantics of two only words in Chinese: zhǐ (只) and éryǐ (而已). I’ve put up a handout of some of this material in work-in-progress form which I recently presented at SNEWS.

I’ll fit right in. ↩
Sexier title suggestions welcome. ↩

Related posts brought to you by Yet Another Related Posts Plugin.

Jetpacking in Boston

mitcho — Sat, 13 Mar 2010 21:19:06 +0000

A couple weeks ago I gave a talk at the Boston Javascript meetup introducing Jetpack and filling people in in the latest developments in the project, including the Reboot. Between 20 to 30 people came to the talk which was at Microsoft Cambridge. Here are the slides from the talk:¹

Extend the Browser with Jetpack

I felt the audience was very engaged and we had almost a dozen questions in the question period and throughout. Most of the examples centered around the use of capabilities and the new security model. For example:

What level of granularity will the manifests have? Do you have to just say “I use xhr” or “I talk to twitter but not facebook”?
What will be the review process for capabilities?
What license will capabilities use?

Perhaps I simply did not present this material in the clearest manner (it didn’t help that I didn’t have any particular slides covering the capability and manifest model) but it also reflects the reality that these particulars of the manifests’ security sections are still being fleshed out. I’m looking forward to the next time I speak on Jetpack when hopefully the discussion of the Reboot will be more concrete and I’ll be able to give a clearer overview and demo of these aspects of the Reboot.

If anyone would like the Keynote deck, just let me know. ↩

Related posts brought to you by Yet Another Related Posts Plugin.

Jetpack Ambassadors in MV

mitcho — Sun, 21 Feb 2010 20:55:23 +0000

A couple weeks ago I went out to Mozilla HQ in Mountain View for a Jetpack Ambassador meetup. Jetpack is a project at Mozilla labs intended to make writing Firefox add-ons easier, and shares some ancestry with the Ubiquity project dear to my heart. The Jetpack Ambassadors are a team of Mozilla community members who will be involved with Jetpack marketing, evangelizing Jetpack and writing about our own experiences working with the exciting new Jetpack architecture.

We spent a good chunk of time with a team from Invisible Elephant who came in to give us some training on making technical presentations, and then dug into the code on Day 2. It was great to have the geniuses at Mozilla Labs like Atul and Myk show us the latest Jetpack code as well as get the latest project direction from Daniel, Aza, and Nick, from which we could see the amount of careful consideration and effort that’s gone into the Jetpack reboot.

The best part of the whole experience, though, has to be the fellowship with the other Jetpack Ambassadors. The Ambassadors came from all over the world, encompassing Europe, Asia, S. America, and of course N. America. Each are involved with some really exciting projects and have each made a name for themselves in their respective communities. I’ve put together a twitter list of all the Jetpack Ambassadors and the core team members and invite you to follow them.

We also had the greatest number of Ubiquity core developers to have ever been in the same place at the same time, which of course had to be documented.

(More photos can be seen in my gallery.)

I had a fantastic time in MV and it was a shame I could only be there for such a short time. I feel honored to be a part of this group and am looking forward to speaking on Jetpack soon at an event near you!

Related posts brought to you by Yet Another Related Posts Plugin.

Mashing up the browser in Maine

mitcho — Sat, 19 Dec 2009 19:00:32 +0000

Last week I was invited to give a talk at the TechMaine annual conference in Portland, Maine.

Being a longer time slot than I previously have used to talk about Ubiquity, I decided to dedicate a good portion of the talk to Jetpack. Being outside of Mozilla for the past few months, this gave me an opportunity to get reacquainted with the Jetpack APIs. I myself was impressed by how easy it was to develop a quick Jetpack. I ended up preparing two to live-code during the talk: one called Helvetica which, with one click, replaces all fonts on the current page with Helvetica; and You Are Here which uses an open API from IPinfoDB to display the physical location of the domain you are currently visiting in the status bar. Both are now on the Jetpack Gallery.

Unfortunately there was a bit of a snowstorm leading up to the event, but there was still a nice turnout and I got to meet some fantastic people there. Ken Shoemake of slerp and quaternion fame came up to me after my talk and said “the Ubiquity parser reminded me of the dancing bear… it’s less surprising that it works well as that it works at all.” I also enjoyed the other great presentations in the technology track, covering the virtues of REST and basic iPhone development.

Mashup the Browser with Ubiquity and Jetpack

Related posts brought to you by Yet Another Related Posts Plugin.