Tu primera extensión

Nota: Si estás familiarizado/a con los conceptos básicos de las extensiones de navegador, omite esta sección y ve a cómo se ponen juntos los archivos. Entonces, usa la documentación de referencia para empezar a construir tu extensión. Visita el Firefox Extension Workshop para aprender más sobre el flujo de trabajo para probar y publicar extensiones para Firefox.

En este artículo abordaremos la creación de una extensión para Firefox, desde el comienzo hasta el final. La extensión solo agrega un borde rojo a cualquiera de las páginas cargadas desde "mozilla.org" o cualquiera de sus subdominios.

El código fuente de este ejemplo se encuentra en GitHub: https://github.com/mdn/webextensions-examples/tree/master/borderify.

Primero, necesitas tener instalado Firefox versión 45 o superior.

Escribiendo la extensión

Crea una nuevo directorio y navega a él. Por ejemplo, en tu línea de comandos/terminal se hace de esta manera:

bash
mkdir borderify
cd borderify

manifest.json

Ahora crearemos un archivo nuevo llamado "manifest.json" directamente en la carpeta "borderify". Añádale el siguiente contenido:

json
{
  "manifest_version": 2,
  "name": "Borderify",
  "version": "1.0",

  "description": "Agrega un borde rojo a todas las páginas web de mozilla.org.",

  "icons": {
    "48": "icons/border-48.png"
  },

  "content_scripts": [
    {
      "matches": ["*://*.mozilla.org/*"],
      "js": ["borderify.js"]
    }
  ]
}
  • Los primeros 3 parámetros:manifest_version, name, y version, son obligatorios, y contienen metadatos básicos para la extensión.
  • description es opcional, pero se recomienda: Se muestra en el Administrador de Add-ons.
  • icons es opcional, pero recomendado: permite especificar un ícono para la extensión, se mostrará en el Administrador de Add-ons.

El parámetro más interesante aquí es content_scripts, el cual le dice a Firefox que cargue el script en las páginas Web, cuyas URL coincidan con un patrón especifico. En este caso, le estamos pidiendo a Firefox que cargue el script llamado "borderify.js" en todas las paginas HTTP o HTTPS cargadas desde "mozilla.org" o cualquiera de sus subdominios.

Advertencia: En algunas situaciones usted necesita especificar un ID para su extensión. Si necesita especificar un ID para el complemento, incluya el parámetro applications en el manifest.json y configure la propiedad gecko.id:

json
"applications": {
  "gecko": {
    "id": "borderify@example.com"
  }
}

icons/border-48.png

La extensión debería tener un ícono. Este se mostrará junto al listado de extensiones en el Administrador de Add-ons. Nuestro manifest.json promete que tendremos un ícono en el directorio "icons/border-48.png".

Crea el directorio "icons" dentro de la carpeta "borderify". Almacena ahí el icono y nómbralo "border-48.png". Puedes utilizar el de nuestro ejemplo, el cual se obtuvo a partir del Google Material Design iconset, y es utilizado bajo los términos de la licencia Creative Commons Attribution-ShareAlike.

Si eliges emplear tu propio icono, este debe ser de 48x48 pixeles. También puedes aplicar un icono de 96x96 pixeles, para resoluciones mayores, y si haces esto, se especifica como la propiedad 96 en el objeto icons del manifest.json:

json
"icons": {
  "48": "icons/border-48.png",
  "96": "icons/border-96.png"
}

Alternativamente, puedes aplicar un archivo SVG ahí, y este se escalará apropiadamente. (Aunque: si usas SVG y tu icono incluye texto, puedes usar la herramienta "convert to path" del editor SVG para aplanar el texto, de modo que se escalone con un tamaño/posición coherente).

borderify.js

Finalmente, crea un archivo de nombre "borderify.js" directamente en el directorio "borderify". Y déjale el siguiente contenido:

js
document.body.style.border = "5px solid red";

Este script se cargara en las páginas que coincidan con el patrón dado en el parámetro content_scripts del archivo manifest.json. El script tiene acceso directo al documento, de la misma manera que los scripts cargados por la propia página.

Probándolo

Primero, verifica que tienes todos los archivos en su lugar:

borderify/
    icons/
        border-48.png
    borderify.js
    manifest.json

Instalación

Abre "about:debugging" en Firefox, da click en "Cargar complemento temporal" y selecciona cualquier archivo en el directorio de la extensión:

La extensión se encontrará instalada, y lo estará hasta que reinicies Firefox.

Alternativamente, puede ejecutar la extensión desde la línea de comandos utilizando la herramienta web-ext.

Probando

Ahora pruebe visitando una página bajo "mozilla.org", y usted verá el borde rojo alrededor de la página:

Nota: No lo intentes en addons.mozilla.org! Los scripts de contenido están actualmente bloqueados en ese dominio.

Experimenta un poco. Edita el contenido del script para cambiar el color del borde, o haz algo más en el contenido de la página. Si actualizas el script de contenido, recarga los archivos de la extensión haciendo clic en el botón "Recargar" en about:debugging. Podrás ver los cambios en el momento:

Empaquetar y publicar

Para que otras personas puedan utilizar tu extensión, necesitas empaquetarlo y enviarlo a Mozilla para que lo firmen. Para que aprendas más sobre eso, mira "Publicando tu extension".

¿Qué sigue?