Cependant, cette transition peut présenter des défis, notamment l'obsolescence de core/jquery.once
, une bibliothèque retirée à partir de Drupal 10.
Drupal a décidé de se libérer de la dépendance à jQuery pour la fonctionnalité "once". Cette décision s'inscrit dans une volonté plus large de modernisation du framework. Ainsi, à partir de Drupal 9.3.0, core/jquery.once
a été déclarée obsolète, pour être complètement retirée dans Drupal 10.
La nouvelle implémentation, réalisée en JavaScript vanilla, est maintenant disponible via la librairie core/once
de Drupal.
once
La librairie once
offre quatre fonctions principales :
once
(équivalent à jQuery.fn.once)once.filter
(équivalent à jQuery.fn.findOnce)once.remove
(équivalent à jQuery.fn.removeOnce)once.find
(nouvelle fonction sans équivalent jQuery)Les fonctions once
prennent généralement deux paramètres :
La syntaxe recommandée est similaire à celle de querySelectorAll()
. Notez que once
ne fonctionne qu'avec des instances de Element, excluant ainsi document
et window
.
Pour une documentation complète, consultez la page npm de l'API once.
Sélectionne les éléments non encore "onced" et ajoute l'identifiant à l'attribut data-once
.
const elements = once('myfeature', '[data-myfeature]');
Filtre et retourne les éléments déjà "onced" avec l'identifiant spécifié.
const filteredElements = once.filter('myfeature', '[data-myfeature]');
Supprime l'identifiant de l'attribut data-once
et retourne les éléments correspondants.
const removedElements = once.remove('myfeature', '[data-myfeature]');
Recherche dans le DOM les éléments déjà "onced" avec l'identifiant spécifié.
const oncedElements = once.find('myfeature');
once
Pour tirer le meilleur parti de la nouvelle API once
, voici quelques bonnes pratiques à suivre :
once
de manière cohérente dans tout votre code pour éviter les comportements inattendus.once
. Par exemple, utilisez 'myModule-featureName' plutôt que des noms génériques.once
de manière excessive. Réservez-le aux opérations qui doivent vraiment être exécutées une seule fois par élément.once.find()
pour des sélections répétées d'éléments déjà traités.once.remove()
lorsque vous devez réinitialiser un comportement.// Bon exemple once('myModule-tooltipInit', '.tooltip', context).forEach(element => { initTooltip(element); }); // À éviter once('init', '.multiple-elements', context).forEach(element => { // Opérations multiples et non liées });
Le passage de jQuery.once
à l'API native once
apporte des améliorations notables en termes de performances :
Ces améliorations contribuent à des temps de chargement plus rapides et une meilleure réactivité des sites Drupal, particulièrement bénéfiques pour les utilisateurs sur des appareils ou connexions moins performants.
Si vous rencontrez cette erreur lors de la mise à niveau vers Drupal 10, suivez ces étapes :
Remplacez core/jquery.once
par core/once
dans les dépendances :
dependencies: - core/jquery - core/once
Modifiez vos appels à la fonction once
dans vos thèmes et modules personnalisés :
Avant :
const $timezone = $(context).find('.timezone-detect').once('timezone');
Après :
const $timezone = $(once('timezone', '.timezone-detect', context));
Pour les sites très volumineux ou anciens où la modification de tous les fichiers JavaScript serait trop complexe, il existe une solution temporaire :
Le module jQuery Once peut être utilisé pour rétablir la fonctionnalité jQuery.once
dans Drupal 10.
composer require 'drupal/jquery_once:^1.0'
Après l'installation, assurez-vous d'inclure la dépendance dans vos fichiers *.libraries.yml
:
dependencies: - jquery_once/jquery.once
Cependant, il est important de noter que cette approche n'est pas recommandée à long terme et devrait être considérée uniquement comme une mesure transitoire.