Getting started

with Mozilla's Add-on SDK

FSOSS, October 29th 2011

Follow along

This talk is a website!

http://talks.canuckistani.ca/fsoss/#2

...and on github

A Brief History

• The Jetpack project started in Mozilla Labs in 2009
• Goals:
  • No XUL / XBL.
  • Make add-on development more like web development.
  • Reduce maintenance burden on add-on developers.

Current release: SDK 1.2

• 1.0 Released June, 2011
• 1.2.1 released Oct 19, 2011:
  • stabilization release
  • Adds some functionality to existing APIs

Next release: 1.3 on Nov. 29.

• Every 6 weeks, 3 weeks before Firefox
• 3 week period to allow for complications and add-on re-pack testing.

Current State

• Goal is to allow very easy implementation of simple add-ons
• Additional functionality can be implemented via modules
• SDK 1.x currently contains a useful but incomplete range of modules
• Obvious advantages:
  • Always restart-less
  • high-level JavaScript APIs
  • packaging tool
  • integrated test framework
  • extensibility via modules using CommonJS format.
  • Future-proof!

Roadmap

• Top priorities:
  • Localization
  • Electrolysis
  • Mobile
• Secondary priorities:
  • better support for existing add-on developers
  • SDK simplification
  • missing pieces: Prefs, Sidebar, Add-on Tab, Tab Groups
  • more missing pieces: minimal / packed xpis, restart-less testing
  • Hug the web harder.

Who's using the SDK?

• 357 total SDK-based add-ons: [link]
• 26% of new add-ons are based on the SDK: [link]
• Most are relatively simple add-ons eg URL shorteners.
• 1Password from Agilebits uses the SDK
  

Mozilla uses the SDK

Mozilla Labs projects currently using the SDK:

• Firefox Share
• Open Web Apps
• Deuxdrop

Mozilla adds features to Firefox via add-ons, using the SDK

Let's Get set up!

Local development

Requirements:

• install Python ( for Windows users )
• any reasonable text editor

Set-up

• Download the SDK and unzip, or
• Use the source: https://github.com/mozilla/addon-sdk
• In a console window:
  • cd /path/to/SDK
  • source bin/activate

Online development with Builder

• Requirements:
  • Firefox
  • AMO account
  • Builder 'helper' add-on
• Benefits:
  • in-browser development
  • create and share re-usable modules
  • planned: publish to AMO

Hacking with the SDK

Style notes

Basic JS style similar in feel to Node.js

1. require('some-module')
2. create a new instance; pass in an options object
3. Rock out!

var someModule = require("some-module");
var instance = someModule.someClass({
  thisoption: 'my option',
  thatoption: 42,
  onSomeEvent: function(data) {},
});
instance.someMethod();

Addon-kit Module overview

• Web content
  • windows, tabs, pag-mod
• User interface & interaction
  • widget, panel, selection, context-menu
• OS integration
  • notifications, selection, clipboard, hotkeys
• Services & data:
  • request, simple-storage, page-worker
• Utilities:
  • timers, passwords, private-browsing

Code, plz kthxbai

Content scripts

• inject any JavaScript logic into a page:
  • inline JS code
  • your own scripts and libraries
  • 3rd party JS libraries such as jQuery
• modify the page's DOM
• communicate from the content script back to your add-on code

Simple Example: Page Exterminator

var data = require("self").data;

var pageMod = require("page-mod").PageMod({
  include: ['http://talks.canuckistani.ca/*'],
  contentScript: 'if (confirm("EXTERMINATE???")) ' + 
    '{ document.body.innerHTML = ' +
    '\'<img src="http://dailypop.files.wordpress.com/2010/04/dalek.gif">\';' + 
    'document.body.style.display="block"; ' + 
    '};',
  contentScriptWhen: 'end',
});

Anatomy of this page-mod

1. include: ['http://talks.canuckistani.ca/*']
   A string url pattern, or array of url patterns.
2. contentScript: "..."
   A string of JavaScript code to run.
3. contentScriptWhen: 'end'
   When do we run this code? The default is 'end', meaning that the script is not run until the page is done loading

Context Meu

var cm = require("context-menu");
cm.Item({
  label: "Context Menu Test",
  context: cm.URLContext('http://aer.local:8080/fsoss*'),
  contentScript: 'self.on("click", function (node, data) {' +
                 '  alert("Click on context menu!"); ' +
                 '});',
  onMessage: function() {
    tabs.activeTab
  }
});

Widget

require("widget").Widget({
    id: "mozilla-icon",
    label: "This is the widget demo!",
    contentURL: "http://www.mozilla.org/favicon.ico",
    panel: xPanel
});

var xPanel = require("panel").Panel({
    height: 340,
    width: 600,
    contentURL: 'http://www.reddit.com/r/programming/.compact'
});

Show a Panel

content script:

$("#panelify").click(function() {
    self.port.emit('panelify', true);
    return false;
});

main.js:

var xPanel = require("panel").Panel({
    height: 340,
    width: 600,
    contentURL: 'http://www.reddit.com/r/programming/.compact'
});

/* pop up the panel */
worker.port.on('panelify', function(m) {
  xPanel.show();
});

Make a Web Request

var shorten = function(url, callback) {    
    let requestJSON = JSON.stringify({longUrl: url});
    let googlRequest = require("request").Request({
        url: 'https://www.googleapis.com/urlshortener/v1/url',
        content: requestJSON,
        contentType: 'application/json',
        onComplete: function(response) {
          callback(response.json);
        }
    });
    googlRequest.post();
}

Show a Notification

content script:

$("#notify").click(function() {
    self.port.emit('notify', true);
    return false;
}); 

main.js:

worker.port.on('notify', function(m) {
  require("notifications").notify({
    title:  "hello from Growl!",
    text:   "of course, you need Growl installed for this to work...",
    iconUrl: "http://www.mozilla.org/favicon.ico"
  });
});

Rocketeers!!

• IRC: #jetpack on irc.mozilla.org
• Google Group
• Weekly project meetings
• Subscribe to Planet Jetpack
• @mozillajetpack
• Mozilla BOF, Saturday afternoon.

Q&A