Creando una extensión

Introducción

Este tutorial contiene los pasos necesarios para desarrollar una extensión muy básica - la cuál añadirá un texto que diga "¡Hola, mundo!" en el panel de la barra de estado del navegador Firefox

Preparando el Entorno de Desarrollo

Las extensiones se distribuyen en archivos comprimidos en formato ZIP, o en paquetes, con extensión xpi (se pronuncia “zippy”). Los archivos XPI contienen el siguiente código:

extension.xpi:
              /install.rdf                   
              /components/*  
              /components/cmdline.js                   
              /defaults/
              /defaults/preferences/*.js     
              /plugins/*                        
              /chrome.manifest                
              /chrome/icons/default/*       
              /chrome/
              /chrome/content/
     

Debido a esto, es más fácil presentar nuestros archivos fuente en un modo similar, a menos que decidamos crear alguno del tipo "Makefile" o un script "shell" para comprimirlos todos. Incluso si optamos por este método, es muy sencillo hacer pruebas, gracias al sistema de Addons de Firefox 1.5.

Aclarado esto comenzamos. Crea una carpeta para tu extensión en algún lugar de tu disco duro, e.j. C:\extensions\my_extension\ o ~/extensions/my_extension/. (Nota: usa todos los caracteres en minúscula) Dentro de esta carpeta creamos otra carpeta llamada chrome, dentro de chrome creamos otra carpeta llamada content. (En sistemas Unix podemos crear los 3 directorios con el siguiente comando mkdir -p chrome/content dentro del directorio de raíz de la extensión.)

Dentro de la raíz de la carpeta extensión, junto a la carpeta chrome, creamos dos archivos de textos vacíos, uno llamado chrome.manifest y el otro install.rdf.

Deberías tener algo así:

<carpeta extension>\
          install.rdf
          chrome.manifest
          chrome\
             content\

Puedes encontrar más tips (ideas) sobre la configuración del ambiente de desarrollo en Mozillazine Knowledge Base.

Crear el manifiesto de la instalación

Abre el archivo llamado install.rdf que creaste en la carpeta raíz de tu extensión y escribe lo siguiente en él:

<?xml version="1.0"?>

<RDF xmlns="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="https://www.mozilla.org/2004/em-rdf#">

  <Description about="urn:mozilla:install-manifest">
    <em:id>[email protected]</em:id>
    <em:version>1.0</em:version>
    <em:type>2</em:type>
   
    <!-- Target Application this extension can install into, 
         with minimum and maximum supported versions. --> 
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>1.0+</em:minVersion>
        <em:maxVersion>1.5.0.*</em:maxVersion>
      </Description>
    </em:targetApplication>
   
    <!-- Front End MetaData -->
    <em:name>¡Ejemplo!</em:name>
    <em:description>Una extensión de prueba</em:description>
    <em:creator>Tu nombre aquí</em:creator>
    <em:homepageURL>https://www.foo.com/</em:homepageURL>
  </Description>      
</RDF>

• [email protected] - la ID de tu extensión. Esta es una clave que has creado para identificar tu extensión en formato de correo electrónico (nota: esta clave no debería ser tu email). Hazla única. Otra opción es usar un GUID.
• Especifica <em:type>2</em:type> -- el 2 indica que una extensión está siendo descrita (mira en Instalar el manifest#tipo para ver los otros códigos).
• {ec8030f7-c20a-464f-9b0e-13a3a9e97384} - La ID del programa Firefox.
• 1.0+ - indica la versión mínima de Firefox con la que afirmas que tu extensión funcionará. Establece ésta como la versión mínima con la que te comprometes a comprobar y corregir errores.
• 1.5.0.* - indica la versión máxima de Firefox con la que afirmas que tu extensión funcionará. ¡Establece ésta como no superior a la máxima versión que esté disponible!

Mira Instalar el manifest para una relación completa de las propiedades tanto obligatorias como opcionales.

Guarda el archivo.

Ampliando el navegador con XUL

La interfaz de usuario de Firefox está escrita en XUL y Javascript. XUL es una implementación XML que proporciona elementos de la interfaz de usuario como botones, menús, barras de botones etc. Las acciones del usuario se controlan mediante JavaScript. Para ampliar el navegador modificamos o añadimos elementos de la interfaz de usuario. Añadimos nuevos elementos mediante la inserción de nuevos elementos XUL DOM dentro de la ventana del navegador, y los modificamos usando scripts e incluyendo manejadores de eventos.

El navegador está definido en un archivo XUL llamado browser.xul ($FIREFOX_INSTALL_DIR/chrome/browser.jar que incluye content/browser/browser.xul). En el archivo browser.xul podemos encontrar la barra de estado, definida en aproximadamente estos términos:

<statusbar id="status-bar">
 ... <statusbarpanel>s ...
</statusbar>

<statusbar id="status-bar"> es un "punto de anclaje" para una capa XUL.

Capas XUL

Capas XUL son una manera de añadir un elemento a la interfaz de usuario en un documento XUL durante el tiempo de ejecución. Una capa XUL es un archivo .xul que marca elementos XUL para insertar en puntos de anclaje específicos dentro del "documento maestro". Estos fragmentos indican que los elementos pueden ser añadidos, modificados o eliminados.

Ejemplo de documento de capa XUL

<?xml version="1.0"?>
<overlay id="sample" 
         xmlns="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 <statusbar id="status-bar">
  <statusbarpanel id="my-panel" label="Hello, World"/>
 </statusbar>
</overlay>

El <statusbar> llamado status-bar indica el punto de anclaje dentro de la ventana del navegador donde lo queremos incluir.

El <statusbarpanel> hijo es un nuevo elemento que queremos insertar en el punto de anclaje.

Copia el código de ejemplo arriba mostrado y guardaló en un archivo llamado sample.xul dentro de la carpeta chrome/content que creó.

Para más información sobre elementos de inserción y modificar la interfaz de usuario empleando Capas, mira más abajo.

Chrome URIs

Los archivos XUL forman parte de "Chrome Packages" - paquetes de componentes de interfaz del usuario, los cuales se cargan a través de la dirección chrome:// URIs. Más que cargar el navegador desde el disco utilizando un (archivo) file:// URI (ya que la ubicación de Firefox en un sistema puede cambiar de una plataforma a otra y de un sistema a otro), los desarrolladores de Mozilla se decantaron por una solución para crear URI al contexto de XUL,que la aplicación instalada ya conoce.

La ventana del navegador es: chrome://browser/content/browser.xul ¡Prueba a teclear esta dirección URL en la barra de navegación de Firefox!

Los Chrome URIs constan de varios componentes:

• En primer lugar, la URI scheme Esquema URI (chrome) informa a la librería de red de Firefox de que es un 'Chrome URI' y que el contenido que se cargue debe ser manejado de manera especial.
• En segundo lugar, un nombre de paquete (en el ejemplo superior utilizamos browser), que identifica la extension en la interfaz del usuario. Este nombre debe ser, en un caso ideal, único, de esa manera se evitará el conflicto entre extensiones.
• En tercer lugar, el tipo de información que ofrece el archivo. Hay tres tipos: content (XUL, JavaScript, XBLs, etc. que forman la estructura y el comportamiento de una aplicación UI), locale (DTD, archivos .propiedades, etc., que contienen cadenas para la localization del UI), y skin (CSS e imágenes que forman el theme del UI)
• En último lugar, la ruta del archivo a cargar.

Por lo tanto, chrome://foo/skin/bar.png carga el archivo bar.png de la sección skin, del tema foo.

Cuando cargas contenido usando un Chrome URI, Firefox usa el Chrome Registry para traducir esos URIs en los archivos fuentes en el disco (o en paquetes JAR).

Creando un Chrome manifest

Para más información sobre el Chrome manifest y las propiedades que soporta, mira la referencia Chrome Manifest.

Abre el archivo llamado chrome.manifest que creaste en el directorio chrome en la raìz de la jerarquía de la carpeta orìgen de la extensión

Agrega este código:

content     sample    chrome/content/

(¡No te olvides de la barra oblicua, "/"! sin ella, la extensión no se cargará.)

Esto especifica lo siguiente:

1. Tipo de material dentro de un paquete chrome.
2. Nombre del paquete chrome (Asegúrate de usar todos los caracteres en minúscula para el nombre del paquete "sample", ya que Firefox/Thunderbird no lo soporta en la versión 2 y anteriores - bug 132183)
3. Localización de los archivos del paquete chrome.

Esta línea dice que para obtener una muestra del paquete chrome, debemos encontrar los archivos de content en la ruta chrome/content, la cual es relativa a la ruta de chrome.manifest.

Nótese que el contenido, los archivos de idioma y los del skin, deben mantenerse dentro de carpetas llamadas content (para contenido), locale (para idioma) y skin dentro de tu subdirectorio chrome.

Salva los cambios del archivo. Cuando inicies Firefox con tu extensión, (lo cual se hará despues en este tutorial), aquel-Firefox- registrará el chrome del paquete.

Registrar un Overlay

Necesitas que Firefox fusione tu overlay con la ventana del browser cada vez que se muestra, por lo que añade esta línea a tu archivo chrome.manifest:

overlay chrome://browser/content/browser.xul chrome://sample/content/sample.xul

Esto le dice a Firefox que fusione sample.xul con browser.xul cuando browser.xul se cargue.

Pruebas

Primero, necesitamos informar a Firefox acerca de tu extensión. En los malos y viejos tiempos de Firefox 1.0, ésto significaba empaquetar tu extensión como un XPI e instalarlo a través de la interfaz de usuario, lo que era engorroso. Ahora es mucho más simple.

1. Abre tu carpeta Profiles y adentrate en el perfil con el que deseas trabajar (e.g. Firefox/Profiles/<profile_id>.default/).
2. Abre la carpeta extensions (creala si ésta no existe)
3. Crea un nuevo archivo de texto, y añade la ruta de la carpeta que contiene tu extensión, e.g. C:\extensions\my_extension\ o ~/extensions/my_extension. Guarda el archivo con el identificador de tu extensión como nombre de archivo, e.g. [email protected]

¡¡Ahora estás preparado para comprobar tu extensión!!

Ejecuta Firefox. Firefox detectará el vínculo de texto al directorio de tu extensión y la instalará. Cuando la ventana del navegador aparezca verás el texto "Hello, World!" en el lado derecho del panel de la barra de estado.

Ahora puedes retornar al archivo .xul y realizar cambios, reinicia Firefox y éstos se verán reflejados.

Empaquetado

Ahora que tu extensión funciona, puedes empaquetarla para su distribución e instalación.

Comprime con zip los contenidos de las carpetas de tu carpeta (no la carpeta de la extensión en sí misma) y cambia la extensión del archivo de .zip a .xpi. En windows XP, puedes hacer esto fácilmente seleccionando todas las carpetas y subcarpeta de la carpeta de tu extensión, haz click con el botón derecho y selecciona "enviar a" -> "Comprimir carpeta". Se creará un archivo .zip. Renómbralo y ya está.

Ahora sube el archivo .xpi a tu servidor, asegurándote de que se sirve con el tipo mime application/x-xpinstall. Haciendo un hipervínculo al archivo puedes permitir a la gente que descargue e instale tu extensión en Firefox.

Usando addons.mozilla.org

En el sitio de distribución Mozilla Update puedes subir tus extensiones totalmente gratis. Tus extensiones serán alojadas en los mirrors de la red Mozilla para garantizar la transferencia directa aún cuando pueda ser muy popular su descarga. La web de Mozilla proporciona a los usuarios una instalación sencilla, y podrán automáticamente disponer de las ultimas versiones que hagas de tu extensión. Además Mozilla Update permite que los usuarios comenten y hagan mejoras sobre tu extensión. ¡Es muy recomendable que utilices Mozilla Update para distribuir tus extensiones!

¡Visita https://addons.mozilla.org/developers/ para crear una cuenta y comenzar a distribuir tu extensión!

Nota: Tu extensión será aceptada y descargada más rápidamente si tiene una buena descripción y algunas imágenes en uso.

Colocación de extensiones en el registro de Windows

En Windows, la información sobre las extensiones se puede agregar al registro, y dicha extensión será automáticamente seleccionada la próxima vez que se ejecute la aplicación. Esto permite que los instaladores de la aplicación integren fácilmente la extensión. Ver Agregar una Extensión usando el Registro de Windows para más información.

Más sobre las capas XUL

Además de añadir elementos de la interfaz de usuario en el punto de anclaje, puede emplear fragmentos XUL dentro de las capas para:

• Cambiar atributos en el punto de anclaje, e.g. <statusbar id="status-bar" hidden="true"/> (esconde la barra de estado)
• Eliminar el punto de anclaje del documento maestro, e.g. <statusbar id="status-bar" removeelement="true"/>
• Controlar la posición de los elementos insertados:

<statusbarpanel position="1" .../>

<statusbarpanel insertbefore="other-id" .../>

<statusbarpanel insertafter="other-id" .../>

Creando nuevos componentes de la interfaz de usuario

Puedes crear tus propias ventanas y cajas de diálogo separadas de los archivos .xul, proporcionar funcionalidad colocando acciones del usuario en ejecución en archivos .js , usar métodos DOM para manipular UI widgets. Puedes usar las reglas de estilos .css, adjuntar imágenes, cambiar colores, etc.

Ver la guía XUL contiene más recursos para desarrolladores XUL.

Archivos por defecto

Los archivos por defecto son utilizados para crear un perfil de usuario y se crean en la carpeta defaults/ que se encuentra dentro de la carpeta raíz de tu extensión. Los archivos .js se deben almacenar dentro de defaults/preferences/ - al ser almacenados aquí serán cargados automáticamente por el sistema de preferencias de Firefox- de modo que se pueda tener acceso mediante las Preferences API.

Componente XPCOM

Firefox soporta el uso del componente XPCOM en extensiones. Puedes crear tus propios componentes fácilmente usando JavaScript o C++ (usando el Gecko SDK).

Coloca todos tus archivos .js o .dll en el directorio components/- para que sean automáticamente registrados la primera vez que inicie Firefox después de instalada la extensión.

Para más información revisa How to Build an XPCOM Component in Javascript y el libro Creating XPCOM Components.

Comandos de la aplicación

Una de las ventajas de las aplicaciones que usan el componente XPCOM es la de poder usar líneas de comandos para su ejecución tanto en Firefox como en Thunderbird. Puedes utilizar esta técnica para correr tus extensiones:

 firefox.exe -myapp

I should move the useful parts of this to the Command Line page. -Nickolay This is done by adding a component containing the function... function NSGetModule(comMgr, fileSpec) { return myAppHandlerModule; } This function is run by firefox each time firefox is started. Firefox registers the myAppHandlerModule's by calling its 'registerSelf()'. Then it obtains the myAppHandlerModule's handler factory via 'getClassObject()'. The handler factory is then used to create the handle using its 'createInstance(). Finally, the handle's 'handle(cmdline)' processes the command line cmdline's handleFlagWithParam() and handleFlag(). Ver Chrome: Command Line o visitar forum discussion para más detalles.

Ubicación

Para permitir más de un lenguaje, debes separar las cadenas del contenido usando entities y string bundles. ¡Es mucho más fácil de hacer esto cuando estás desarrollando tu extensión que volver y hacerlo luego!

La información de la ubicación está almacenada en el directorio locale para las extensiones. Por ejemplo, para agregar un locale para nuestra extensión de prueba, crea un directorio llamado "locale" en chrome (donde esta ubicado el "contenido" del directorio) y agrega las siguientes líneas al archivo chrome.manifest:

locale sample sampleLocale chrome/locale/

Para crear valores de atributos ubicables en XUL, pones los valores en un archivo .ent (o un .dtd), el cual deberá ponerse en el directorio locale y verse así:

<!ENTITY  button.label     "Clickeame!">
<!ENTITY  button.accesskey "C">

Y entonces inclúyelo en la parte superior del documento XUL (pero debajo de: "<?xml version"1.0"?>") quedando asi:

<!DOCTYPE window SYSTEM "chrome://packagename/locale/filename.ent">

Donde window es el localName del elemento raíz del documento XUL, y el valor de la propiedad SYSTEM es la URI de chorme al archivo entity. Para nuestra extensión de ejemplo, el elemento de la raíz es overlay.

Para usar entities, tu XUL debe verse asi:

<button label="&button.label;" accesskey="&button.accesskey;"/>

El registro de Chrome se asegurara que el archivo entity ha sido cargado del paquete correspondiente a la localizacion elegida.

Para las lineas que usarás en tu script, crea un archivo .properties; un archivo de texto que contendrá estas líneas:

key=value

Entonces usa el tag nsIStringBundleService/nsIStringBundle o el tag <stringbundle> para cargar los valores en el script.

Comprender el navegador

Utiliza DOM Inspector (no es parte de la instalación Estandar de Firefox, debes reinstalar seleccionando instalación personalizada y elegir Herramientas de Desarrollo si no hay un elemento "Inspector de DOM" en el menu Herramientas del browser) para inspeccionar la ventana del browser o cualquier otra ventana XUL que quieras extender.

Utiliza el botón de búsqueda apuntar-y-clic situado en la parte superior izquierda de la barra de herramientas de DOM Inspector visualmente en un nodo de la ventana XUL para seleccionarlo. Cuando hagas esto DOM Inspector ira dentro del árbor jerárquico al nodo sobre el que hiciste clic.

Utiliza el panel lateral derecho de DOM Inspector para descubrir los puntos de anclaje con los ids que puedes utilzar para insertar tus elementos en los overlays. Si no pudieses encontrar un elemento con un id sobre el que hacer la mezcla, puedes añadir un script en tu overlay e insertar tus elementos cuando el evento load se dispare en la ventana XUL maestra.

Depurar extensiones

Herramientas analitícas para Depurar (Debugging)

• El DOM Inspector - inspecciona atributos, estructura del DOM, reglas de estilos CSS que están afectando (ej. buscar-porque sus reglas de estilo parecen no estar trabajando para un elemento -, ¡una herramienta invaluable!)
• Venkman - Marca de control (breakpoints) en JavaScript e inspeccionar la pila de llamada.
• arguments.callee.caller en JavaScript - accede a la pila de llamada de funciones.

printf debugging

• Ejecutar Firefox con -console en la linea de comandos y usar

dump("string") (ver el enlace para detalles)

• Usar nsIConsoleService para ingresar/invocar la consola JavaScript

Depuración avanzada

• Ejecutar una “construcción” de Firefox de depuración y establecer los puntos de interrupción en el propio Firefox, o sus componentes C++. Para el desarrollador experimentado, esta es a menudo la manera más rápida de diagnosticar un problema. Para más información ver Build Documentation y Developing Mozilla.

• Para obtener mas consejos útiles ver Debugging a XULRunner Application.

Guía Rápida

Otro tutorial desde MozillaZine Knowledge Base, también puedes bajar este archivo para usarlo como base en la creación de tus extensiones helloworld.zip.