Primeros pasos

Este tutorial recorre los pasos para la creación de un add-on simple usando el SDK.

Requisitos previos

Para crear add-ons para Firefox usando el SDK, primero es necesario seguir las instrucciones para instalar y activar el SDK. Una vez hecho esto, se debe ir directamente a la terminal.

Inicializar un add-on vacío

En la terminal, cree un directorio nuevo. El directorio no tiene que estar bajo la raíz del SDK: puede crearlo donde quiera. Dirijase al directorio recién creado, escriba cfx init, y presione la tecla enter o intro:

mkdir my-addon
cd my-addon
cfx init

Visualizará una salida como esta:

* lib directory created
* data directory created
* test directory created
* doc directory created
* README.md written
* package.json written
* test/test-main.js written
* lib/main.js written
* doc/main.md written
Your sample add-on is now ready for testing:
try "cfx test" and then "cfx run". Have fun!"

Implementar el add-on

Ahora puede escribir el código del add-on, el cual se ubica en el archivo "main.js" en el directorio "lib". Este archivo fue creado en el paso anterior. Abra este archivo y agrege el siguiente código:

var buttons = require('sdk/ui/button/action');
var tabs = require("sdk/tabs");

var button = buttons.ActionButton({
  id: "mozilla-link",
  label: "Visit Mozilla",
  icon: {
    "16": "./icon-16.png",
    "32": "./icon-32.png",
    "64": "./icon-64.png"
  },
  onClick: handleClick
});

function handleClick(state) {
  tabs.open("https://www.mozilla.org/");
}

Guarde los cambios.

Luego, guarde estos tres iconos en el directorio "data" :

	icon-16.png
	icon-32.png
	icon-64.png

Vuelva a la terminal y escriba:

cfx run

Esta es la orden del SDK para ejecutar una nueva instancia de Firefox con el add-on instalado. Cuando el Firefox es presentado, en la esquina superior derecha se puede ver un ícono con el logo de Firefox. Al hacer clic en el ícono, se abrirá una pestaña nueva donde se cargará la página https://www.mozilla.org/.

A given cfx option has an inappropriate value:
  ZIP does not support timestamps before 1980

touch icon-16.png

Esto es todo lo que este add-on hace. Usa dos módulos del SDK: el módulo action button, el cual permite agregar botones al navegador, y el módulo tabs, el cual permite llevar a cabo operaciones básicas con las pestañas. En este caso, se ha creado un botón cuyo icono es el logo de Firefox, y se le agregó un controlador que carga la página principal de Mozilla en una nueva pestaña al hacer clic en el icono.

Intente editar este archivo. Por ejemplo, puede cambiar la página que es cargada:

var buttons = require('sdk/ui/button/action');
var tabs = require("sdk/tabs");

var button = buttons.ActionButton({
  id: "mozilla-link",
  label: "Visit Mozilla",
  icon: {
    "16": "./icon-16.png",
    "32": "./icon-32.png",
    "64": "./icon-64.png"
  },
  onClick: handleClick
});

function handleClick(state) {
  tabs.open("https://developer.mozilla.org/");
}

En la terminal, ejecute de nuevo cfx run. Ahora al hacer clic en el ícono se cargará la página https://developer.mozilla.org/.

Empaquetar el add-on

Cuando el add-on este terminado y listo para distribuirse, será necesario empaquetarlo como un archivo XPI. Este es el formato de archivo de instalación para los add-ons de Firefox. Puede distribuir los archivos XPI por cuenta propia o publicarlos en https://addons.mozilla.org para que otros usuarios puedan descargarlos e instalarlos.

Para construir un XPI, solo se debe ejecutar la orden cfx xpi desde el directorio del add-on:

cfx xpi

Visualizará una salida como esta:

Exporting extension to my-addon.xpi.

Para comprobar que funcione, intente instalar el archivo XPI en el Firefox instalado en su sistema. Lo puede hacer presionando la combinación de teclas Ctrl+O (Cmd+O en Mac) desde el Firefox, o seleccionando la opción "Abrir" desde el menú "Archivo" de Firefox. Esto abrirá un diálogo de selección; navegue hasta el archivo "my-addon.xpi", abra el archivo y siga las instrucciones para instalar el add-on.

Resumen

En este tutorial se ha construido y empaquetado un add-on usando tres órdenes:

• cfx init para inicializar una plantilla vacía para el add-on
• cfx run para ejecutar una instancia nueva de Firefox con el add-in instalado, para poder realizar pruebas
• cfx xpi para empaquetar el add-on en un archivo XPI para su distribución

Estas son las tres órdenes principales, usadas cuando se desarrollan add-ons con SDK. Existe una completa documentación de referencia que cubre todas las órdenes que pueden ser usadas y todas sus opciones disponibles.

El código del add-on usa dos módulos del SDK, action button y tabs. Existe una documentación de referencia para todas las APIs de alto-nivel y bajo-nivel en el SDK.

Qué sigue?

Para tener una idea de lo que se puede hacer con las APIs del SDK, puede revisar alguno de estos tutoriales.

Técnicas avanzadas

Sobrescribiendo los módulos integrados

Los módulos del SDK que son usados para implementar un add-on están integrados en Firefox. Cuando se ejecuta o empaqueta un add-on usando cfx run o cfx xpi, el add-on usará las versiones de los módulos de la versión de Firefox que los aloja.

Como desarrollador de add-on, esto es usualmente lo deseable. Pero si esta desarrollando los módulos del SDK, por supuesto, que no lo es. En este caso se asume que se accedió al SDK desde el repositorio de GitHub y se ejecutó la secuencia de comandos bin/activate desde la raíz de checkout.

Luego al aplicar cfx run or cfx xpi, se agrega la opción "-o":

cfx run -o

Esto le indica a cfx a usar las copias locales de los módulos del SDK, y no aquellas en Firefox.

Desarrollar sin cfx run

Debido a que cfx run reinicia el navegador cada vez que es invocado, en ocasiones puede resultar un poco incómodo si se realizan cambios frecuentes al add-on. Un modelo alternativo de desarrollo es usar el add-on Extension Auto-Installer: el cual esta atento a la existencia de nuevos archivos XPI en un puerto determinado y los instala automáticamente. De esta manera se pueden probar los cambios realizados sin necesidad de reiniciar el navegador:

• haga un cambio en el add-on
• ejecute cfx xpi
• coloque el add-on al puerto especificado

Incluso, se puede automatizar este proceso con una simple secuencia de comandos. Por ejemplo:

while true ; do cfx xpi ; wget --post-file=codesy.xpi https://localhost:8888/ ; sleep 5 ; done

Nótese que el nivel de acceso definido para la terminal cuando se usa este método es diferente, comparado con el nivel de acceso usado cuando un add-on es ejecutado usando cfx run. Esto significa que si se desea ver la salida desde los mensajes de  console.log(), se debe modificar la configuración. Vea la documentación en niveles de acceso para más detalles.

Otra alternativa es con el uso de grunt y grunt-shell:

module.exports = function(grunt) {
  'use strict';
  require('matchdep').filterDev('grunt-!(cli)').forEach(grunt.loadNpmTasks);
  grunt.initConfig({
    shell: {
      xpi: {
        command: [
          'cd pluginpath',
          'cfx xpi',
          'wget --post-file=pluginname.xpi https://localhost:8888/ || echo>/dev/null'
        ].join('&&')
      }
    },
    watch: {
      xpi: {
        files: ['pluginpath/**'],
        tasks: ['shell:xpi']
      }
    }
  });

  grunt.loadNpmTasks('grunt-contrib-watch');
  grunt.loadNpmTasks('grunt-shell');
  grunt.registerTask('default', ['watch']);
};