Tutorial: cómo utilizar la librería once() en Drupal

Cómo funciona Once

Para mostrar el funcionamiento de la librería Once, utilizaremos el siguiente ejemplo:

const myElements = once('myCustomEvent', '.my-select', context);
myElements.forEach(element => {
  element.on('change', function() {
    $.ajax({
      method: "POST",
      url: "/update-user",
      data: { 
        name: "Sandra", 
        location: "Barcelona" 
      },
      dataType: "json"
    })
    .done(function(data) {
      console.log("Success!");
      console.log(data);
    });
  });
});

Como se puede ver, es un pequeño código que ejecuta una llamada AJAX cada vez que el usuario cambia el valor de un campo desplegable, un <select>. El problema aquí es que si usamos Drupal.behaviors y no limitamos la acción de este código con Once, la llamada se ejecutará cada vez que otros procesos asíncronos de Drupal se ejecuten también. Y evidentemente, no es eso lo que queremos en este caso. 

Pero examinemos más detalladamente el código para entender mejor en qué puede ayudarnos esta librería:

• La variable myElements crea una variable para el elemento con el que quieres trabajar. Está en plural, porque la función once siempre devuelve un conjunto. Podrías hacer algo como const [element] para devolver solo un elemento, si estás seguro de que ese elemento del DOM que estás buscando en la página es único. Sin embargo, es mejor devolver el conjunto, por si acaso en el futuro hay una segunda instancia con el mismo selector en la página.
• once() es la función que asegurará que el código que actúa sobre tu elemento (o elementos) del DOM solo actúe una vez.
• myCustomEvent es un nombre arbitrario que asignamos a este elemento. Puedes asignar prácticamente cualquier cosa, como whateverYouWant. Esto se vincula a la propiedad en tu DOM mediante un atributo de datos, como data-once="myCustomEvent", de manera que JavaScript sabe a qué función once pertenece este elemento.
• context es simplemente el método que se utilizará para encontrar el conjunto. Podrías utilizar document aquí, pero si la página se actualiza mediante AJAX, entonces document no se actualizará. Así que, en términos de Drupal, context probablemente sea la mejor opción que tenemos.

Dependencias para usar Once

Recuerda, siempre que uses once, incluirla como dependencia en tu librería en Drupal:

my-library:
  dependencies:
    - core/once

Bonus: snippets para Visual Studio Code

Aquí tienes unos snippets para codificar de manera más rápida once en tu editor Visual Studio Code:

{
  "once drupal behavior (one element)": {
    "prefix": "oncedrupal",
    "body": "const [${1:element}] = once('${2:once-string}', '${3:selector}', context);\nif (${1:element}) {\n// code \n}",
    "description": "once drupal behavior (one element)"
  },
  "once drupal behavior (array foreach)": {
    "prefix": "oncedrupal",
    "body": "const ${1:array} = once('${2:once-string}', '${3:selector}', context);\n${1:array}.forEach(${4:element} => {\n// code \n});",
    "description": "once drupal behavior (array foreach)"
  },
  "once drupal behavior (array for of)": {
    "prefix": "oncedrupal",
    "body": "const ${1:array} = once('${2:once-string}', '${3:selector}', context);\nfor (const ${4:element} of ${1:array}) {\n// code \n};",
    "description": "once drupal behavior (array for of)"
  }
}