Comment utiliser les événements JavaScript d'Advanced Search dans mon thème ou mon module ?

À partir de la version 5.4.0, Advanced Search expose ses événements JavaScript via le système d'événements natif de PrestaShop, en plus des événements jQuery existants. Votre thème ou un autre module peut écouter ces événements pour réagir aux changements de filtres ou actualiser ses propres composants après une mise à jour de la recherche.

Cette intégration est disponible dans la version standard et dans la version PRO, sur les boutiques où le système d'événements natif de PrestaShop est disponible. Les événements propres à une fonctionnalité PRO, comme le passage d'une étape, nécessitent cette fonctionnalité.

Cette FAQ s'adresse aux développeurs et intégrateurs de thèmes. Ajoutez le code dans un fichier JavaScript chargé par votre thème ou votre module d'intégration.

Écouter les événements via le système natif de PrestaShop

Utilisez prestashop.on() avec le nom exact de l'événement. L'exemple suivant s'exécute lorsqu'Advanced Search a terminé la mise en place de l'affichage des résultats :

if (typeof prestashop !== 'undefined' && typeof prestashop.on === 'function') {
    prestashop.on('as4-After-Set-Results-Contents', function (idSearch, context) {
        console.log('Résultats Advanced Search mis à jour', idSearch, context);
        // Réinitialisez ici les composants personnalisés de votre thème si nécessaire.
    });
}

Le callback reçoit l'identifiant du moteur de recherche, puis la valeur de contexte fournie par le module. Ce contexte identifie le chemin de mise à jour utilisé par le module, par exemple showAsResponse ; il ne s'agit ni du HTML de la réponse ni d'un objet événement du navigateur.

Pour réagir à un changement de critère, vous pouvez utiliser :

prestashop.on('as4-Criterion-Change', function (idSearch, idCriterionGroup, value, label, controlType) {
    console.log('Critère modifié', idSearch, idCriterionGroup, value, label, controlType);
});

Chargez ce second exemple uniquement après la mise à disposition du système d'événements de PrestaShop, comme dans le premier exemple.

Événements disponibles

Les noms d'événements conservent leur préfixe historique as4-, y compris dans Advanced Search 5. Respectez exactement les noms et les majuscules indiqués.

idSearch identifie le moteur de recherche et idCriterionGroup son groupe de critères. Ces identifiants sont utiles lorsque plusieurs moteurs sont présents sur une même page. searchMethod et stepSearch contiennent les valeurs du mode de recherche courant utilisées par le module.

Pour as4-Criterion-Change, les arguments dépendent du contrôle : controlType peut valoir link, select, checkbox ou range. La valeur peut être une valeur unique ou un tableau pour une sélection multiple ; les changements d'intervalle numérique peuvent transmettre null pour la valeur et le libellé. Ces arguments ne contiennent pas l'ensemble de la sélection de recherche, et un changement dans un contrôle ne garantit pas à lui seul qu'une nouvelle liste de produits a déjà été affichée.

L'événement Before-Set-Results-Contents marque l'entrée dans la routine de mise en place de l'affichage des résultats. Il ne garantit pas que le HTML de la liste de produits précédente est encore présent.

Les écouteurs jQuery existants fonctionnent-ils toujours ?

Oui. Les événements jQuery existants restent pris en charge. Un écouteur comme celui-ci continue de fonctionner :

$(document).on('as4-After-Set-Results-Contents', function (event, idSearch, context) {
    console.log('Résultats Advanced Search mis à jour', idSearch, context);
});

Les signatures des callbacks sont différentes : jQuery fournit d'abord un objet événement, suivi des arguments du module. Un écouteur enregistré avec prestashop.on() reçoit uniquement les arguments du module, sans objet événement en premier paramètre. Si vous adaptez un écouteur existant au système natif, modifiez ses paramètres en conséquence.

Choisissez un seul système d'événements pour chaque action. Enregistrer la même action à la fois avec jQuery et avec prestashop.on() l'exécutera deux fois, car le module émet via les deux systèmes.

Quand enregistrer les écouteurs ?

Enregistrez-les une seule fois, après la mise à disposition du système d'événements de PrestaShop et avant les événements que vous souhaitez observer. Pour écouter l'initialisation des blocs lors du premier chargement, l'écouteur doit être enregistré avant cette initialisation : les événements passés ne sont pas rejoués.

Les blocs de recherche et leur contenu peuvent être initialisés à nouveau après des mises à jour. Évitez d'enregistrer une nouvelle copie du même écouteur à chaque callback de recherche et prévoyez que l'initialisation de vos composants puisse être exécutée plusieurs fois. Pour intégrer un traitement lié à l'affichage des résultats, utilisez un événement adapté à cet affichage et filtrez sur idSearch si votre action concerne un moteur particulier.