Mobile Add-on development using the Add-on SDK

For this post, please welcome guest blogger and SDK developer Matteo Ferretti who has been hard at work porting the SDK to work with the new native version of Mobile Firefox.

Getting Started

Add-on SDK version 1.5 is due to be released on February 21st, and we're pleased to announce that this version will introduce initial support for creating addons for the new native version of Firefox Mobile (codename "fennec").
Mobile support is still experimental and is currently focused on addons using the SDK's page-mod module to alter and interact with web pages.

If you're interested in trying this support out now, you can do so by checking out the ‘master’ branch of the addon-sdk repository:

git clone git://github.com/mozilla/addon-sdk.git

Alternatively you can just download a zip archive of the current master:

https://github.com/mozilla/addon-sdk/zipball/master

Developing an add-on for Firefox Mobile with the Add-on SDK is very similar to the desktop. If you're not familiar with Add-on SDK development process, you can take a look here. It helps but is not mandatory for this tutorial.

Getting set up

In addition to having the correct version of the SDK, there are some additional requirements:

• you need to have an Android device connected to your computer via USB
• on the Android device, you need to install a Nightly build of Firefox Mobile.
• you need to download and install the Android SDK, including the SDK Tools. Specifically, the SDK requires that you have installed the 'adb' command-line tool.

Please see this detailed tutorial by Aaron Train for more information on installing and configuring the Android SDK.

Now you're ready to write the classic "Hello World" example!

Hello, Fennec!

Firstly, be sure that you have connected your device to your computer. You can check it running from a shell the following command:

adb devices

Then, be sure that you don't have any Firefox Mobile already running. That is important because the Add-on SDK will run your add-on using a temporary firefox profile for development, not the default one. If Firefox is already running, you can quit Firefox by opening the application menu, selecting 'More', then selecting 'Quit'.
Don't worry, if Firefox is running the Add-on SDK will clearly warn you.

Now open a shell, navigate to the Add-on SDK root directory, and execute:

source bin/activate

This will activate the SDK's environment and allow you to run the cfx tool from the current shell prompt nomatter what directory you are currently in..

Change to another directory and then create a directory called hellofennec. Keeping your add-on code outside the SDK is good practice. Navigate to that directory and run cfx init to create a new addon:

mkdir hellofennec
cd hellofennec
cfx init

With a text editor or IDE of your choice, open lib/main.js, and replace its contents with the following:

console.log("Hello, Fennec!");

Save it. You're ready to run it on your device using the following command:

cfx run -a fennec-on-device -b ~/path/to/adb --mobile-app fennec --force-mobile

And yes, compared to the desktop version the mobile version needs more arguments. You can learn about all the cfx's arguments just run it without any parameters, but let's have a quick look about what they means in this context:

• -a, –app : specify the application that runs the add-on, in this case "fennec on device".

• -b, –binary : is mandatory for fennec-on-device app. SDK needs to know where you have installed the adb tool that is installed with the Android SDK in order to communicate with your device. So, replace this value with the right path where you have installed the adb platform tool.

• –mobile-app : is the name of the Android intent. If you have only one Firefox Mobile version installed on your device, you can omit this option. The value for nightly is fennec, for aurora this is fennec_aurora, for beta this is firefox_beta and for release this is firefox.
  If you have a Fennec's custom build on your device, the intent's name is fennec_<your_username> by default.

• –force-mobile : this flag will be removed when the mobile's support will be stable and not experimental anymore.

When you execute the command the first time you'll see a message like this:

No 'id' in package.json: creating a new ID for you.
package.json modified: please re-run 'cfx run'

Run the command again, and it will run Firefox Mobile on your device with your add-on installed.

Congratulations! You have made your first step in mobile add-ons development with Add-on SDK!

Hack the web

As I said previously, Add-on SDK provide a minimal support for mobile at the moment, focused mainly on page-mod. In short, they are add-ons that can modify any — or a specific — web pages loaded by the browser.

On mobile this is very handy. For instance, you can optimize a website that it wasn't designed for mobile devices, improve the readability, or adding unique functionality.

For this tutorial I made a simple add-on that "mod" the famous penny-arcade.com website. You can check it out from github:

git clone git://github.com/ZER0/penny-arcade-comics.git

Alternatively, you can download it as zip archive.

What it does is simple: when you're on the penny-arcade.com homepage or reading a news post, switching from portrait to landscape will display the webcomics related to that news, without clicking a link and zooming (landscape fits more the format of penny-arcade comics than portrait, and portrait is more suitable to reading news). Switching back from landscape to portrait will hide it again.

A deeper look

So, how it works? The important files are data/content.css, data/content.js and main.js. The first two are the files injected into penny-arcade.com, and the last one is our add-on entry point.
Let's start with main.js.
Firstly, we require the Add-on SDK modules needed:

var PageMod = require("page-mod").PageMod;
var data = require("self").data;

The PageMod object allows us to create a page-mod; and data object provides an access to the data directory's files.

PageMod({
  // page-mod will added only on the homepage and news page of penny-arcade.com,
  // with or without www as prefix.
  include: /^http:\/\/(www\.)?penny-arcade.com(\/|\/\d{4})?.*/,
  contentScriptFile: data.url("content.js"),
  contentScriptWhen: "ready",
  onAttach: function (worker) {
    worker.port.emit("init", data.url("content.css"));
  }
});

For the main.js, that's all. The addon will load content.js into the page when the DOM is ready for any URL that matches the include property's regular expression. When the page-mod is "attached" to a document, the onAttach callback will emit a custom init event to the content script, passing the URL of content.css.

So, what happens on the other side when the init event is emitted? Let's see content.js:

self.port.on("init", function init(cssURL) {
  // We're not interested in frames
  if (window.frameElement) return;
  addStyleSheet(cssURL);
  var comicsPageURL = document.querySelector(".btnComic").href;
  var http = new XMLHttpRequest();
  http.open("GET", comicsPageURL, true);
  http.onload = addComics;
  http.send();
});

A page-mod is attached to every page that matches the include rule, so frames as well. We are not interested in frames, only in the main page, so with:

if (window.frameElement) return;

We avoid to execute code in that specific case.

Then, we add the stylesheet given using addStyleSheet function, defined in the same file, and we obtain the comics page URL by looking into the DOM.
Because the comic page and the news page are in the same domain, we can use XMLHttpRequest from the content script itself (content scripts follows the Same Origin Policy) instead of having to delegate this task to the Add-on code (that can perform Cross Domain requests).
When we receive the response, the comic page's image url is extracted and displayed in the current page. And that's all!

The behavior related to hide and display the comics image is implemented in css file using media queries:

@media (orientation:portrait) {
  #penny-arcade-addon-comics {
    display: none;
  }
}
@media (orientation:landscape) {
  #penny-arcade-addon-comics {
    display: block;
  }
}

See the results

Navigate into the penny-arcade-comics directory and run it. You should see Fennec Nightly or Aurora ( whichever you specified ) start up on your device. Next, open the Firefox menu, select 'More', then 'Addons'. You should see the list of default addons installed into Firefox, as well as two additions: 'Mobile Addon-SDK utility addon' and 'penny-arcade-comics'.

You can now see how it works at first hand by opening the Penny Arcade site ( http://penny-arcade.com/ ) in Firefox Mobile:

Portrait

Landscape

If you do not have an Android device to test this on, you can still see the effect by installing this addon on Firefox Desktop and re-sizing the window to trigger the media queries we've used in our customer css.

When running the addon on your deivce, you will notice that your shell will be full of javascript warnings; this is because cfx will dump all of Firefox's log messages there. They can be useful, but especially when you work with page-mod it's easy lost your add-on's logging information in this flow. What I usually do instead is open a new shell, and execute a command like that:

adb logcat | grep info:

So, in the shell where cfx is executing I will get all the messages, and in the other one I filtered out only the messages from the add-on.

Conclusion

We're very excited about the possibilities around mobile addons and would love any feedback you might have. Working with the Android SDK currently is a bit awkwards, admittedly. If you do get started creating your own addons for Fennec Nightly, please keep in mind that not all SDK modules work properly.
The modules that currently work are:

• page-mod
• page-worker
• request
• self
• simple-storage
• timers

There are additional modules that mostly work; we are currently working on providing as much support for mobile as possible and will keep you up to date on our progress.