Tutorial: com fer servir la llibreria once() al teu Drupal

Com funciona Once

Per tal de mostrar el funcionament de la llibreria Once, farem servir el següent exemple:

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);
    });
  });
});

Com es pot veure, és un petit codi que executa un crida AJAX cada vegada que l'usuari canvia el valor d'un camp despegable, d'un <select>. El problema aquí és que si fem servir Drupal.behaviors i no limitem l'acció d'aquest codi amb Once, la crida s'executarà cada vegada que d'altres processos asíncrons de Drupal s'executin també. I evidentment, no és això el que volem en aquest cas. 

Però examinem més detalladament el codi per entendre millor en què pot ajudar-nos aquesta llibreria:

• La variable myElements crea una variable per a l'element amb el que vols treballar. És en plural, perquè la funció once sempre retorna un conjunt. Podries fer alguna cosa com const [element] per a retornar només un element, si estàs segur que aquell element del DOM que estàs cercant a la pàgina és únic. No obstant això, és millor retornar el conjunt, per si de cas en el futur hi ha una segona instància amb ek mateix selector a la pàgina.
• once() és la funció que assegurarà que el codi que actua sobre el teu element (o elements) del DOM només actuï una vegada.
• myCustomEvent és un nom arbitrari que assignem a aquest element. Pots assignar-hi pràcticament qualsevol cosa, com ara whateverYouWant. Això es vincula a la propietat en el teu DOM mitjançant un atribut de dades, com ara data-once="myCustomEvent", de manera que JavaScript sap a quina funció once pertany aquest element.
• context és simplement el mètode que s'utilitzarà per trobar el conjunt. Podries utilitzar document aquí, però si la pàgina es actualitza mitjançant AJAX, llavors document no s'actualitzarà. Així doncs, en termes de Drupal, context probablement és la millor opció que tenim.

Dependències per utilitzar Once

Recordeu, sempre que utilitzeu once, de incloure-la com a dependència a la vostra llibreria al Drupal:

my-library:
  dependencies:
    - core/once

Bonus: snippets per a Visual Studio Code

Aqui teniu uns snippets per codificar d'una manera més ràpida once al vostre 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)"
  }
}