Implementar una página de configuración
=======================================

Una página de configuración ofrece a los usuarios una manera de ver y cambiar los ajustes (algunas veces también llamados "preferencias" u "opciones") para el complemento.

Con WebExtensions, los ajustes generalmente se almacenan utilizando la API `storage` . La implementación de una página de configuración se realiza en un proceso de tres pasos:

* Escribir un archivo HTML que muestre los ajustes y permita al usuario cambiarlos.
* Escribir un script, incluido desde el archivo HTML , que establece la página de configuración desde su almacenamiento y actualiza los ajustes seleccionados cuando el usuario los modifica.
* Establecer la ruta al archivo HTML como la clave `options_ui` (en-US) en manifest.json. Haciendo esto, el documento HTML se mostrará en el administrador de complementos del navegador, junto al nombre del complemento y su descripción.

**Nota:** También puedes abrir esta página mediante programación utilizando la función `runtime.openOptionsPage()` (en-US) .

Una sencilla ExtensionWeb
-------------------------

En primer lugar, vamos a escribir una extensión que añada un borde azul a todas las páginas que el usuario visita.

Crea un nuevo directorio llamado "configuración", a continuación crea un archivo llamado"manifest.json" en su interior ,con el siguiente contenido:


```json
{
  "manifest\_version": 2,
  "name": "Settings example",
  "version": "1.0",

  "content\_scripts": [
    {
      "matches": ["<all\_urls>"],
      "js": ["borderify.js"]
    }
  ],

  "applications": {
    "gecko": {
      "id": "settings-example@mozilla.org"
    }
  }
}
```


Este complemento da instrucciones al navegador para cargar un script de contenido llamado "borderify.js" en todas las páginas web que el usuario visita.

Ten en cuenta que también hemos incluido la clave `applications` (en-US) . Necesitaremos esto (solamente en Firefox ) porque si hay un error, debemos establecer explícitamente (la identidad del complemento) add-on ID , y también incluimos la clave de manifiesto `options_ui`. Aunque no utilicemos la clave `options_ui` en ese momento, lo haremos en la siguiente sección. Ver el bug 1269545.

A continuación, crea un archivo llamado "borderify.js" en el directorio "configuración" , y añade el siguiente contenido :


```js
document.body.style.border = "10px solid blue";
```


Esto solo añade un borde azul a la página.

Ahora instala WebExtension y comprueba — abre cualquier página web que te guste:

Añadir ajustes
--------------

Ahora vamos a crear una página de configuración que permita al usuario establecer el color del borde.

En primer lugar, actualiza "manifest.json" para que tenga este contenido:


```json
{
  "manifest\_version": 2,
  "name": "Settings example",
  "version": "1.0",

  "content\_scripts": [
    {
      "matches": ["<all\_urls>"],
      "js": ["borderify.js"]
    }
  ],

  "applications": {
    "gecko": {
      "id": "settings-example@mozilla.org"
    }
  },

  "options\_ui": {
    "page": "options.html"
  },

  "permissions": ["storage"]
}
```


Hemos añadido dos nuevas claves de manifiesto:

* `options_ui` (en-US): Esta establece un documento HTML que es la página de configuración (tambien llamada página de opciones) para este complemento.
* `permissions` (en-US): utilizaremos la API `storage` para almacenar los ajustes, y necesitaremos pedir permiso para utilizar esta API.

A continuacion, como hemos prometido crear "options.html", vamos a realizarlo. Crea un archivo con ese nombre en el directorio "configuración" , y añade el siguiente contenido:


```html
<!doctype html>

<html>
  <head>
    <meta charset="utf-8" />
  </head>

  <body>
    <form>
      <label>Border color<input type="text" id="color" /></label>
      <button type="submit">Save</button>
    </form>

    <script src="options.js"></script>
  </body>
</html>
```


Esto define un elemento HTML `<form>` con un texto etiquetado `<input>` y un botón de envio `<button>`. también incluye un script llamado "options.js".

Crea "options.js", de nuevo en el directorio "configuración" , y añade el siguiente contenido:


```js
function saveOptions(e) {
  chrome.storage.local.set({
    color: document.querySelector("#color").value,
  });
}

function restoreOptions() {
  chrome.storage.local.get("color", (res) => {
    document.querySelector("#color").value = res.color || "blue";
  });
}

document.addEventListener("DOMContentLoaded", restoreOptions);
document.querySelector("form").addEventListener("submit", saveOptions);
```


Esto hace dos cosas:

* Cuando el documento ha sido cargado, se obtiene el valor "color" desde el almacenamiento utilizando `storage.local.get()` (en-US). Si el valor no se ha establecido, utiliza por defecto "azul".
* Cuando el usuario envía el formulario haciendo click en "guardar", se almacena el valor del cuadro de texto utilizando `storage.local.set()` (en-US).

Finalmente, actualiza "borderify.js" para leer el color del borde del almacenamiento:


```js
chrome.storage.local.get(null, (res) => {
  var color = "blue";
  if (res.color) {
    color = res.color;
  }
  document.body.style.border = "10px solid " + color;
});
```


En este punto, el complemento completo debe tener este aspecto:
```

settings/
    borderify.js
    manifest.json
    options.html
    options.js
```


Ahora:

* recarga WebExtension.
* carga una página web.
* abre la página de configuración y cambia el color del borde.
* recarga la página web para ver la diferencia.

En Firefox se puede accededer a la página de configuración visitando : complementos y haciendo click en el botón "Preferencias" junto a la entrada del complemento.

Aprende más
-----------

* Documentación de referencia de la clave de manifiesto.options\_ui. (en-US)
* Documentación de referencia de la API storage.
* Abrir la página de configuración directamente desde el complemento utilizando la API `runtime.openOptionsPage().` (en-US)
* Página de ejemplo de configuraciones:
    + color-favorito.