Tutorial

En este articulo vamos a ver paso por paso como se crea una WebExtension para Firefox, desde el inicio hasta el final.

La extensión añade un nuevo botón a la barra de herramientas de Firefox. Cuando el usuario da clic sobre el botón, mostraremos una ventana emergente que permite escoger un animal. Una vez que un animal sea escogido, reemplazaremos todas las imágenes en la página actual con la imagen del animal seleccionado.

Para implementar esto, haremos lo siguiente:

• Definir una acción del navegador, que será el botón añadido a la barra de herramientas de Firefox.
  Para el botón vamos a proporcionar:
  • un icono, llamado "beasts.png"
  • una ventana emergente para abrir cuando el botón sea presionado. La  ventana emergente incluye HTML, CSS y JavaScript.
• Escribe un script de contenido, "beastify.js" que será inyectado dentro de las páginas web.
  Este es el código que modificará las páginas web.
• Empaqueta algunas imágenes de animales, para reemplazar las imágnes de la página web.
  Nosotros haremos las imágenes "recursos web accesibles" para que la página web pueda referenciarlos.

Tu puedes notar que la estructura general de la extensión luce como esto:

Esta es una extensión extremadamente simple, pero muestra muchos de los principales conceptos de la API WebExtensions:

• Adicionando un botón a la barra de herramientas
• Definiendo un panel emergente usando HTML, CSS y JavaScript
• Inyectando scripts de contenido dentro de las páginas web
• Comunicándonos entre los scripts de contenido y el resto de la extensión
• Empaquetando recursos con tu extensión que pueden ser usados por las páginas web

Tu puedes encontrar el código fuente completo de la extensión en GitHub.

Prerequisitos

Para desarrollar usando las APIs de WebExtension, debes seguir algunos pasos antes de comenzar.

• Descarga, instala, y ejecuta Firefox para Desarrolladores o Firefox Nightly. Usa Nightly si quieres tener los últimos cambios.
• Ve a la preferencia que controla la instalación de complementos no firmados. Nota que esta preferencia solo está disponible en Firefox para Desarrolladores y Firefox Nightly.
  • Escribe about:config dentro de la barra de direcciones de Firefox
  • En el campo de búsqueda escribe xpinstall.signatures.required
  • Has doble clic sobre la preferencia, o clic derecho y escoge Modificar, para cambiarla a false.

Escribiendo la WebExtension

Crea una carpeta nueva y navega hacia ella:

mkdir beastify
cd beastify

manifest.json

Ahora crea un archivo llamado "manifest.json", y agrega el siguiente contenido:

{

  "manifest_version": 2,
  "name": "Beastify",
  "version": "1.0",

  "applications": {
    "gecko": {
      "id": "[email protected]"
    }
  },

  "permissions": [
    "https://*/*",
    "https://*/*"
  ],  

  "browser_action": {
    "default_icon": "button/beasts.png",
    "default_title": "Beastify",
    "default_popup": "popup/choose_beast.html"
  },
  
  "web_accessible_resources": [
    "beasts/frog.jpg",
    "beasts/turtle.jpg",
    "beasts/snake.jpg"
  ]

}

• Las tres primeras llaves: manifest_version, name, y version, son obligadas y contienen los metadatos básicos para la extensión.
• permissions lista los permisos que la extensión necesita. Nosotros estamos pidiendo permiso para modificar todos las páginas HTTP y HTTPS: mira la documentación de la llave permissions. Nosotros quisiéramos usar aquí el permiso activeTab, pero actualmente no está soportado en Firefox.
• browser_action especifica el botón de la barra de herramientas.  Nosotros proveemos tres piezas de información aquí:
  • default_icon es obligado y enlaza al icono para el botón
  • default_title es opcional y será mostrado como descripción
  • default_popup es usado su tu quieres una ventana emergente que será mostrada cuando el usuario de clic en el botón. Lo hacemos y hemos incluido esta llave que apunta a un archivo HTML de la extensión.
• web_accessible_resources lista los archivos que queremos hacer accesibles a las páginas web. Como la extensión reemplaza imágenes en una página con imágenes que hemos empaquetado, necesitamos hacer estas imágenes accesibles a la página.

Nota que todas las rutas dadas son relativas a manifest.json.

El botón de la barra de herramientas

El botón de la barra de herramientas necesita un icono, y nuestro manifest.json promete eso y nos gustaría tener un icono para el botón en "button/beasts.png".

Crea la carpeta "button" y copia un icono llamado "beasts.png". Tu podrías usar uno de nuestros ejemplos, los cuales son tomados desde el sitio IconBeast y empleados bajo sus términos de licencia.

Si tu no provees una ventana emergente, entonces el evento clic es disparado hacia tu extensión cuando el usuario de clic sobre el botón. Si provees una ventana emergente entonces el evento clic no se disparará, pero en cambio, se muestra la ventana emergente. Nosotros queremos una ventana emergente, así que vamos a crearla.

La ventana emergente

La función de la ventana emergente es habilitada si el usuario escoge una de los tres animales.

Crea una nueva carpeta llamada "popup" bajo la carpeta de la extensión. Esta será donde pondremos el código para la ventana emergente. La carpeta "popup" contendrá estos tres archivos:

• choose_beast.html define el contenido del panel
• choose_beast.css los estilos CSS para el contenido
• choose_beast.js maneja las opciones del usuario ejecutando un script de contenido en la pestaña activa

choose_beast.html

El archivo HTML luce como esto:

<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="choose_beast.css"/>
  </head>

  <body>
    <div class="beast">Frog</div>
    <div class="beast">Turtle</div>
    <div class="beast">Snake</div>

    <script src="choose_beast.js"></script>
  </body>

</html>

Nosotros solo queremos un elemento para cada animal. Nota que hemos incluido CSS y JS desde este archivo, justo como una página web.

choose_beast.css

El CSS ajusta el tamaño de la ventana emergente, se asegura que las tres posibles opciones llenen el espacio y les da un poco de estilo básico:

html, body {
  height: 100px;
  width: 100px;
  margin: 0;
}

.beast {
  height: 30%;
  width: 90%;
  margin: 3% auto;
  padding-top: 6%;
  text-align: center;
  font-size: 1.5em;
  background-color: #E5F2F2;
  cursor: pointer;
}

.beast:hover {
  background-color: #CFF2F2;
}

choose_beast.js

En el JavaScript para la ventana emergente, nosotros escuchamos los eventos clic. Si el clic es sobre alguno de los tres animales, inyectamos un script dentro de pestaña activa. Una vez que el script de contenido es cargado, enviamos a él un mensaje con el animal elegido:

document.addEventListener("click", function(e) {
  if (!e.target.classList.contains("beast")) {
    return;
  }

  var chosenBeast = e.target.textContent;
  
  chrome.tabs.executeScript(null, {
    file: "content_scripts/beastify.js" 
  });

  chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
    chrome.tabs.sendMessage(tabs[0].id, {beast: chosenBeast});
  });

});

Este usa tres funciones de la API WebExtension API:

• chrome.tabs.executeScript para inyectar un script alojado en  "content_scripts/beastify.js" dentro de la pestaña activa
• chrome.tabs.query para obtener la pestaña activa
• chrome.tabs.sendMessage para enviar un mensaje al script ejecutado en la pestaña activa. El mensaje contiene el animal seleccionado en la propiedad beast.

El script de contenido

Crea una carpeta nueva bajo la carpeta de la extensión llamada "content_scripts" y crea un nuevo archivo en ella llamado "beastify.js", con el contenido siguiente:

chrome.runtime.onMessage.addListener(beastify);
 
function beastify(request, sender, sendResponse) {
  var beastURL = beastNameToURL(request.beast);
  var images = document.querySelectorAll("img");
  for (var i = 0; i < images.length; ++i) {
    images[i].setAttribute("src", beastURL);
  }
 
  chrome.runtime.onMessage.removeListener(beastify);
}

function beastNameToURL(beastName) {
  switch (beastName) {
    case "Frog":
      return chrome.extension.getURL("beasts/frog.jpg");
    case "Snake":
      return chrome.extension.getURL("beasts/snake.jpg");
    case "Turtle":
      return chrome.extension.getURL("beasts/turtle.jpg");
  }
}

El script de contenido añade un escuchador para mensajes desde la extensión (específicamente desde "choose_beast.js", arriba). En el escuchador:

• transforma el nombre del animal en una URL que enlaza a la imagen a usar
• encuentra todos los elementos <img> en la página actual
• establece sus atributos src hacia la URL para la imagen
• elimina el escuchador de mensajes.

Los animales

Finalmente, necesitamos incluir las imágenes de los animales.

Crea una carpeta nueva llamada "beasts", y adiciona tres imágenes en ella, con su nombre apropiado. Tu puedes obtener estas imágenes desde el repositorio en GitHub, o desde aquí:

Empaquetando e instalando

Chequea nuevamente que tienes todos los archivos necesarios en el lugar adecuado:

beastify/

    beasts/
        frog.jpg
        snake.jpg
        turtle.jpg

    button/
        beasts.png

    content_scripts/
        beastify.js

    popup/
        choose_beast.css
        choose_beast.html
        choose_beast.js

    manifest.json

Las extensiones para Firefox son empaquetadas como archivos XPI, los cuales son solamente archivos ZIP, con extensión "xpi".

Un truco es que el archivo ZIP debe ser un archivo que contenga los archivos de la extensión y no la carpeta que los contiene. Así que, para crear un XPI, desde una terminal navega hasta la carpeta "beastify" y escribe:

   # in beastify/
   zip -r ../beastify.xpi *

Para instalar el XPI, deber abrirlo en Firefox:

• desde el menú Archivo, selecciona Abrir, o presiona Ctrl/Cmd+O
• selecciona "beastify.xpi" desde dialogo de selección de archivos

Usted debe recibir un aviso de que va a instalar una extensión sin firmar. Acepte la advertencia.

Ahora debes ver el icono aparecer en el barra de herramientas de Firefox. Abre una página web, luego da clic en el botón, selecciona un animal y verás como las imágenes en la página web son cambiadas.