Una WebExtension la compone una colección de archivos, empaquetados para su distribución e instalación. En este artículo vamos a repasar rápidamente los archivos que deben estar presentes en una WebExtension.
Toda WebExtension debe contener un archivo llamado "manifest.json". Este puede tener enlaces a otros cuatro (4) tipos de archivos:
- background pages: implementa la lógica de ejecución
- content scripts: interactúa con las páginas web
- browser action files: implementa los botones de la barra de herramienta
- web accessible resources: hace posible que el contenido empaquetado acceda a páginas web y scripts
manifest.json
Este es el único archivo que debe estar presente en toda WebExtension. Este contiene los metadatos básicos acerca de la extensión, como su nombre, versión, y los permisos que esta requiere. También provee los enlaces a otros archivos de la extensión.
Mira la página de referencia manifest.json para ver todos los detalles.
Scripts en segundo plano
WebExtensions a menudo necesitan mantener estados de larga duración, o ejecutar operaciones a largo plazo, independientemente del tiempo de vida de una página web en particular o las ventanas del navegador. Para eso son los scripts en segundo plano.
Los scripts en segundo plano son cargados cuando la extensión es cargada y se mantienen cargados hasta que la extensión es deshabilitada o desinstalada. Tu puedes usar cualquier API de WebExtensions en el script, You can use any of the WebExtension APIs in the script, siempre y cuando hayas solicitado el permiso necesario.
Especificando los scripts en segundo plano
Tu puedes incluir un script en segundo plano usando la propiedad background en "manifest.json":
// manifest.json
"background": {
"scripts": ["background-script.js"]
}
Tu puedes especificar múltiples scripts en segundo plano: si lo haces, ellos se ejecutarán en el mismo contexto, justo como son cargados múltiples scripts en una página web.
Entorno del script en segundo plano
APIs del DOM
Los scripts en segundo plano se ejecuta en el contexto de páginas especiales llamadas páginas en segundo plano. Esto le da un variable global window, junto con todas las APIs estándar del DOM que proporciona.
Usted no tiene que proveer su propia página en segundo plano. Si incluyes un script en segundo plano, una página en segundo plano vacía se creará para ti.
Sin embargo, tu puedes escoger y proveer tu página en segundo plano como un archivo HTML separado:
// manifest.json
"background": {
"page": "background-page.html"
}
APIs de WebExtension
Los scripts en segundo plano pueden usar cualquier API de WebExtension en el script, siempre que tu extensión tenga los permisos necesarios.
Acceso de origen cruzado/ Cross-origin access
Los scripts en segundo plano puede hacer peticiones XHR a cualquier host para los cuales tiene permisos.
Acciones del navegador / Browser actions
Si tu extensión define una acción del navegador, y esa acción del navegador no tiene ventanas emergentes, entonces puedes escuchar los eventos "clic" del botón en el navegador empleando el objeto onClicked de las acciones del navegador:
chrome.browserAction.onClicked.addListener(handleClick);
Contenido web / Web content
Los scripts en segundo plano no tienen acceso directo a las páginas web. Sin embargo, se puede cargar scripts de contenido dentro de las páginas web, y comunicarse con esos scripts empleando la API de pasos de mensajes.
Scripts de contenido / Content scripts
Usas los scripts de contenido para acceder y manipular páginas web. Los scripts de contenido son cargados dentro de las páginas web y ejecutados en el contexto particular de esa página.
Los scripts de contenido pueden verse y manipular el DOM de las páginas como los scripts normales cargados por la página.
A diferencia de los scripts normales, ellos pueden:
- realizar peticiones XHR de dominio cruzado
- usar un pequeño subconjunto de las APIs de WebExtension
- intercambiar mensajes con sus scripts en segundo plano, y por esta vía, tener acceso indirecto a todas las APIs de WebExtension.
Los scripts de contenido no pueden acceder directamente a los scripts normales de una página web, pero pueden intercambiar mensajes con ellos usando la API estándar window.postMessage().
Generalmente, cuando hablamos acerca de scripts de contenido, nos referimos a JavaScript, pero tu puedes inyectar CSS dentro de las páginas web empleando el mismo mecanismo.
Mira el artículo scripts de contenido para aprender más.
Acciones del navegador / Browser actions
Una acción del navegador es un botón que tu puedes añadir a la barra de herramientas del navegador. Los usuarios puedes dar clic en el botón para interactuar con tu extensión.
Opcionalmente tu puedes definir una ventana emergente para el botón empleando HTML, CSS y JavaScript.
Si tu no defines una ventana emergente, entonces cuando el usuario de clic sobre el botón se disparará un evento hacia la extensión. Si defines una ventana emergente, el evento clic no se disparará: instantáneamente la ventana se mostrará cuando el usuario de clic en el botón, y el usuario podrá interactuar con ella.
Nota que tu extensión solo podrá tener una acción del navegador / browser action.
Especificando la acción del navegador
Tu defines las propiedad de la acción del navegador - icono, título y ventana emergente - a través de la llave browser_action de manifest.json, y puedes cambiar cualquiera de estas propiedades empleando la API browserAction.
Icono
Esta es la imagen para el botón y la única propiedad obligatoria de la llave browser_action.
Tu puedes definir múltiples imágenes de diferentes tamaños: si haces esto, entonces el navegador seleccionará el tamaño apropiado para la resolución de pantalla. Se recomienda que proporciones un icono de 19x19 píxeles y otro de 38x38:
"default_icon": {
"19": "geo-19.png",
"38": "geo-38.png"
}Tu también puedes definir solo una imagen. Si haces esto, el navegador recortará la imagen si es necesario, y quizás esta pueda aparecer borrosa en algunas resoluciones:
"default_icon": "geo.png"Usa la función setIcon() de la API browserAction para cambiar el icono desde el código JavaScript de tu extensión.
Título
Esta es una cadena que se mostrará como descripción cuando el usuario pase el ratón por encima del botón:
"default_title": "Whereami?",Usa la función setTitle() de la API browserAction para cambiar el título desde el código JavaScript de tu extensión.
Ventana emergente
Si la ventana emergente está definida, esta se mostrará cuando el usuario de clic sobre el botón. Esta se especifica en el manifest.json como una ruta hacia el archivo HTML:
"default_popup": "popup/my-popup.html"El archivo HTML puede incluir archivos CSS y JavaScript, como una página web normal. A diferencia de una página web normal, el código JavaScript puede usar todas las APIs de WebExtensions a las que el complemento tenga permisos.
Usa la función setPopup() y la API browserAction para cambiar la ventana emergente desde el código JavaScript de tu extensión.
Escuchando los eventos para clic
Si una acción del navegador no tiene una ventana emergente, entonces cuando el usuario de clic sobre el botón, un evento clic se enviará a la extensión. Los scripts en segundo plano podrán escuchar los eventos usando un código como este:
chrome.browserAction.onClicked.addListener(handleClick);
Aprende más
Para aprender más acerca de las acciones del navegador, mira la página de la API browserAction y la página de la llave browser_action del manifest.json.
Recursos web accesibles
Los recursos web accesibles son recursos como imágenes, HTML, CSS y JavaScript que tu puedes incluir en la extensión y los quieres hacer accesible a los scripts en segundo plano y los scripts de las páginas. Los recursos que son hechos accesibles desde la web pueden ser referenciados desde scripts de páginas web y scripts de contenido mediante un esquema especial de URI.
Por ejemplo, si un script de contenido quiere insertar algunas imágenes dentro de páginas web, tu puedes incluirlos en la extensión y hacerlos accesibles desde la web. El script de contenido creará y añadirá las etiquetas img que referencia a las imágenes mediante el atributo src.