Faire une recherche semi-automatique dans WordPress avec du code

Ce tutoriel est pour vous qui souhaitez implémenter une recherche semi-automatique dans WordPress, où nous contrôlons totalement les correspondances renvoyées.

Nous appliquerons une saisie semi-automatique à la recherche WordPress standard, mais le code est très flexible afin que vous puissiez personnaliser la requête selon vos besoins. Qu’il s’agisse d’une requête plus spécifique par un type de publication personnalisé, une méta de publication, des catégories ou des requêtes sur un type de contenu complètement différent, tel que des utilisateurs ou quelque chose de manuel à partir de la base de données. Vous pouvez également appliquer facilement la saisie semi-automatique sur une entrée de recherche personnalisée au lieu de la recherche WordPress standard.

Ce que nous ferons

La saisie semi-automatique est une zone d’interface utilisateur qui apparaît sous le champ de recherche et affiche les correspondances pendant que vous tapez. En cliquant sur une correspondance, le navigateur vous enverra au lien permanent de cette publication. Cela offre à l’utilisateur final un moyen plus rapide de naviguer dans votre contenu puisqu’il n’aura pas besoin de faire un détour supplémentaire vers votre page de résultats de recherche. Nous utiliserons AJAX pour mettre à jour en continu les correspondances pendant que l’utilisateur tape.

La saisie semi-automatique est générée à l’aide de jQuery UI Autocomplete, un script inclus dans WordPress par défaut.

Configuration du code

Vous devrez ajouter le code dans le functions.phpfichier PHP du thème ou d’un plug-in actif. Ce tutoriel est basé sur son ajout dans un thème. Ajustez les chemins en fonction de votre projet.

La première étape consiste à créer un fichier Javascript qui contiendra notre code pour déclencher la saisie semi-automatique. En ce qui concerne ce tutoriel, je vais créer un fichier vide autocomplete.jsdans le dossier de mon thème assets/js/. L’endroit où vous placez votre fichier dépend de vous, n’oubliez pas d’ajuster les chemins ci-dessous. Nous reviendrons sur ce fichier après l’avoir correctement mis en file d’attente dans WordPress.

Mise en file d’attente des scripts et des styles

Nous devons mettre en file d’attente notre fichier Javascript de saisie semi-automatique et nous devons également nous assurer de mettre en file d’attente jQuery et jQuery UI Autocomplete. De plus, WordPress n’inclut aucun style pour les bibliothèques jQuery UI, nous devons donc également mettre en file d’attente une feuille de style pour jQuery UI à partir de Google CDN. Ceci est facultatif bien sûr. Vous pouvez ajouter le CSS d’une autre manière ou peut-être préférez-vous le styler vous-même.

Nous mettrons en file d’attente tous les scripts et styles dans une fonction accrochée àwp_enqueue_scripts :

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_script('autocomplete-search', get_stylesheet_directory_uri(). '/assets/js/autocomplete.js', 
        ['jquery', 'jquery-ui-autocomplete'], null, true);
});

L’ [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)()appel de fonction ci-dessus ajoutera notre fichier Javascript nouvellement créé avec les dépendances correctes (le tableau en troisième paramètre). Cela garantit que WordPress ajoute les scripts jQuery et jQuery UI Autocomplete dans notre instance WordPress.

Ensuite, nous devons fournir des variables auxquelles nous pouvons accéder à partir de notre script de saisie semi-automatique. Nous avons besoin de connaître l’URL AJAX et nous voulons également ajouter un nonce pour la sécurité. Nous pouvons le faire en utilisant [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)():

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_script('autocomplete-search', get_stylesheet_directory_uri(). '/assets/js/autocomplete.js', 
        ['jquery', 'jquery-ui-autocomplete'], null, true);
    wp_localize_script('autocomplete-search', 'AutocompleteSearch', [
        'ajax_url' => admin_url('admin-ajax.php'),
        'ajax_nonce' => wp_create_nonce('autocompleteSearchNonce')
    ]);
});

La wp_localize_script()fonction créera une variable Javascript globale AutocompleteSearchavec deux propriétés ; ajax_urlet ajax_nonce. Avec cela, nous pouvons dans notre fichier Javascript autocompléter récupérer par exemple la valeur de l’URL WordPress AJAX avec AutocompleteSearch.ajax_url.

Enfin, nous devons ajouter un peu de style. Comme mentionné, WordPress n’inclut aucun style d’interface utilisateur jQuery, nous devons donc en ajouter nous-mêmes. J’ai opté pour l’ajout d’une feuille de style via Google CDN. Mais nous avons besoin de connaître le numéro de version de jQuery UI pour récupérer sa feuille de style. Nous pourrions coder en dur un numéro de version, mais je ne suis pas fan du codage en dur. Vous trouverez ci-dessous une astuce intéressante pour prendre de l’avance sur les informations de version de l’interface utilisateur de jQuery stockées dans WordPress.

add_action('wp_enqueue_scripts', function() {
    ...
 
    $wp_scripts = wp_scripts();
    wp_enqueue_style('jquery-ui-css',
        '//ajax.googleapis.com/ajax/libs/jqueryui/'. $wp_scripts->registered['jquery-ui-autocomplete']->ver. '/themes/smoothness/jquery-ui.css',
        false, null, false
    );
});

Nous utilisons [wp_enqueue_style](https://developer.wordpress.org/reference/functions/wp_enqueue_style/)()pour enregistrer et ajouter une nouvelle feuille de style avec le chemin CDN fourni comme deuxième argument. Afin de récupérer un numéro de version valide de l’interface utilisateur jQuery, nous utilisons les informations fournies par la fonction [wp_scripts](https://developer.wordpress.org/reference/functions/wp_scripts/)().

Et c’est tout ce dont nous avons besoin pour mettre les scripts en file d’attente !

Ecrire le Javascript de saisie semi-automatique

Revenons à notre autocomplete.jsdossier. Nous savons que lorsque ce script est chargé, jQuery et jQuery UI Autocomplete sont déjà chargés, et nous avons également accès à une variable globale avec les informations nécessaires. Commençons par configurer une fonction de prêt de document jQuery pour nous assurer que notre code est exécuté une fois que DOM est prêt.

jQuery(function($) {
    // All code in here
});

Si nous nous référons à la documentation de jQuery UI Autocomplete, nous apprenons que nous devons créer un sélecteur jQuery ciblant un champ de saisie et exécuter la fonction autocomplete()dessus.

C’est un point où vous pouvez modifier le code pour l’adapter à vos besoins. Ce tutoriel appliquera la saisie semi-automatique sur le champ de recherche WordPress standard (qui est généralement ajouté dans le thème en incluant le modèle de recherche ou en tant que widget). Les noms de classe de l’entrée de recherche peuvent varier d’un thème à l’autre. Mais vous souhaiterez peut-être cibler un champ de saisie personnalisé ou effectuer une recherche dans un modèle spécial. Tout ce que vous avez à faire est de changer le sélecteur jQuery pour cibler l’entrée souhaitée.

Dans mon thème, l’entrée de champ de recherche WordPress standard a une classe de .search-field. J’ajoute également le nom de la classe du formulaire parent pour le réduire davantage afin que nous ne risquions pas que la saisie semi-automatique soit appliquée à quelque chose d’autre utilisant la même classe.

Selon la documentation Autocomplete, nous pouvons effectuer un appel AJAX dans la propriété source(qui doit renvoyer un tableau d’éléments à afficher dans l’autocomplete). Nous utiliserons la fonction Ajax de jQuery pour faire exactement cela :

jQuery(function($) {
    $('.search-form .search-field').autocomplete({
        source: function(request, response) {
            $.ajax({
                dataType: 'json',
                url: AutocompleteSearch.ajax_url,
                data: {
                    term: request.term,
                    action: 'autocompleteSearch',
                    security: AutocompleteSearch.ajax_nonce,
                },
                success: function(data) {
                    response(data);
                }
            });
        },
    });
});

À la ligne #2, nous indiquons à jQuery UI Autocomplete sur quel champ de saisie nous voulons appliquer la saisie semi-automatique. Modifiez ce sélecteur selon vos besoins.

Dans la forme la plus simple, Autocomplete attend un tableau d’objets d’élément à la sourcepropriété. Ici, nous créons une fonction avec deux paramètres ; requestcontient des informations sur notre valeur entrée (request.term), et responsequi est une fonction de rappel dont nous avons besoin pour appeler et fournir les données. C’est ce que nous faisons dans la fonction AJAX successà la ligne #13.

L’appel AJAX lui-même est assez standard. Nous définissons le type de données comme JSON – c’est important sinon jQuery UI Autocomplete ne pourra pas analyser les résultats. Lorsque urlnous accédons ajax_urlà la variable globale, nous avons localisé notre script plus tôt ; AutocompleteSearch. Et comme datanous passons devant un objet d’information. La actionpropriété est obligatoire et nécessaire pour l’étape suivante, qui consiste à identifier cette requête AJAX spécifique en PHP. Nous transmettons également le terme saisi dans l’entrée et le nonce pour des raisons de sécurité.

C’est tout pour la sourcespropriété. Il y a une autre chose que nous devons ajouter dans notre script de saisie semi-automatique. Par défaut, dans jQuery UI Autocomplete, le choix d’un élément remplit automatiquement l’entrée avec l’élément choisi. Nous souhaitons rediriger l’utilisateur vers l’URL de la publication lors du choix d’un élément dans la liste. Nous ajoutons donc une fonction à la selectpropriété :

                ...
                success: function(data) {
                    response(data);
                }
            });
        },      
        select: function(event, ui) {
            window.location.href = ui.item.link;
        },
    });
});

Dans le tableau d’éléments que nous reviendrons de notre appel AJAX (nous écrirons ceci ensuite), chaque élément est un objet avec des propriétés. Nous ajouterons une linkpropriété personnalisée à chaque élément (ui.item) qui contiendra les permaliens de chaque article. Nous transmettons cette URL à [window.location.href](https://www.w3schools.com/js/js_window_location.asp)laquelle déclenchera une redirection du navigateur.

Et c’est tout pour la partie Javascript! Il ne reste plus qu’à écrire la partie PHP qui écoute les requêtes AJAX avec l’action autocompleteSearch.

Renvoi des résultats en PHP aux requêtes AJAX

Afin d’écrire des fonctions qui répondent à des requêtes AJAX spécifiques, nous utilisons les crochets wp_ajax_{action}(visiteurs connectés) et wp_ajax_nopriv_{action}(visiteurs non connectés). Nous avons défini l’action comme autocompleteSearchdans notre requête AJAX ci-dessus. Reportez-vous à mon article qui explique le fonctionnement d’AJAX dans WordPress si vous n’êtes pas familier avec cela.

Configurons cela dans functions.php(ou n’importe où dans PHP où vous ajoutez votre code):

add_action('wp_ajax_nopriv_autocompleteSearch', 'awp_autocomplete_search');
add_action('wp_ajax_autocompleteSearch', 'awp_autocomplete_search');
function awp_autocomplete_search() {
    // echo result
    die();
}

Avec le code ci-dessus, nous accrochons la même fonction aux deux crochets AJAX. Dans toutes les fonctions qui sont accrochées aux hooks wp_ajax AJAX, nous devons nous assurer de toujours die()ou exità la fin afin de ne pas faire écho à une sortie indésirable. J’utilise la [wp_die](https://developer.wordpress.org/reference/functions/wp_die/)()fonction de WordPress.

Nous pouvons récupérer les données transmises à partir de Javascript en utilisant $_REQUEST(fonctionne pour les requêtes GET et POST). Dans notre code Javascript, nous avons passé le terme saisi dans la clé ‘ term‘. Cela signifie que nous pouvons en récupérer la valeur dans $_REQUEST['term']. Nous pouvons ensuite effectuer une requête basée sur cela. N’oubliez pas que nous souhaitons uniquement renvoyer les résultats correspondant à ce terme de recherche.

C’est un autre point où vous pouvez entièrement modifier et ajuster le code en fonction de vos besoins. Ce didacticiel effectuera une requête standard sur les publications et les pages, mais vous pouvez modifier la requête ou effectuer une requête complètement différente sur des données différentes. Peut-être préférez-vous ou avez-vous besoin d’effectuer une requête SQL manuelle à la place (c’est certainement plus efficace en mémoire). La partie cruciale ici est le tableau que nous renvoyons à la fin, qui est analysé par le code de saisie semi-automatique de notre Javascript.

add_action('wp_ajax_nopriv_autocompleteSearch', 'awp_autocomplete_search');
add_action('wp_ajax_autocompleteSearch', 'awp_autocomplete_search');
function awp_autocomplete_search() {
    check_ajax_referer('autocompleteSearchNonce', 'security');
    $search_term = $_REQUEST['term'];
    if (!isset($_REQUEST['term'])) {
        echo json_encode([]);
    }
    $suggestions = [];
    $query = new WP_Query([
        's' => $search_term,
        'posts_per_page' => -1,
    ]);
    if ($query->have_posts()) {
        while ($query->have_posts()) {
            $query->the_post();
            $suggestions[] = [
                'id' => get_the_ID(),
                'label' => get_the_title(),
                'link' => get_the_permalink()
            ];
        }
        wp_reset_postdata();
    }
    echo json_encode($suggestions);
    wp_die();
}

Nous vérifions d’abord si le nonce était valide afin d’établir une certaine sécurité sur nos appels AJAX. Nous pouvons le faire en appelant la fonction [check_ajax_referer](https://developer.wordpress.org/reference/functions/check_ajax_referer/)(). J’ai également ajouté du code pour nous assurer que nous n’effectuons pas de requête lourde si le terme de recherche renvoyé était vide. Nous devrions ensuite retourner un tableau vide encodé en json.

L’exemple de code ci-dessus effectue [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)une recherche sur le terme saisi. Nous devons nous assurer posts_per_pageque -1nous renvoyons tous les matchs. Consultez la documentation WP_Querysi vous souhaitez affiner davantage la requête.

Nous parcourons ensuite les résultats (ligne #17) et remplissons un tableau avec des correspondances (ligne #19-23). jQuery UI Autocomplete a besoin au minimum de la propriété labelpour signifier ce qui doit être affiché dans la boîte de saisie semi-automatique. Nous transmettons également les permaliens dans la clé ‘ link‘ qui est ce que nous utilisons dans notre code Javascript pour rediriger l’utilisateur.

Enfin, à la ligne, #27nous faisons écho au tableau généré en tant que JSON en utilisant [json_encode](https://www.php.net/manual/en/function.json-encode.php)().

Avec cette partie PHP en place, notre saisie semi-automatique devrait fonctionner ! Actualisez votre site et essayez-le !

Améliorations facultatives

Un problème courant est que le nombre de correspondances est trop élevé et que la boîte de saisie semi-automatique devient trop grande. Il existe deux solutions à cela.

Une solution consiste à ajouter la propriété minLengthà la autocomplete()fonction en Javascript. Cette propriété ne déclenchera la boîte de saisie semi-automatique qu’après la saisie d’un certain nombre de caractères. Par exemple, nous pouvons exiger un minimum de 3 caractères avant de déclencher la saisie semi-automatique :

        ...
        select: function(event, ui) {
            window.location.href = ui.item.link;
        },
        minLength: 3,
    });
});

jQuery UI Autocomplete propose ici une autre solution. Il montre un exemple d’ajout d’un peu de CSS pour ajouter une hauteur fixe et une barre de défilement interne dans la boîte de saisie semi-automatique.

Conclusion et code complet

Nous avons ajouté avec succès une fonction de saisie semi-automatique à la fonctionnalité de recherche de WordPress où nous avons le contrôle total des correspondances à renvoyer. Cela donne aux visiteurs un moyen plus rapide de naviguer dans votre contenu, car cliquer sur une correspondance redirigera directement vers la publication, plutôt que de faire d’abord un détour dans une page de résultats de recherche. La mise en œuvre d’une saisie semi-automatique n’a pas toujours de sens sur tous les sites WordPress, mais peut être idéale pour rechercher un contenu spécifique ou dans des modèles spéciaux !

Voici le code final dans son intégralité :

add_action('wp_enqueue_scripts', function() {
    wp_enqueue_script('autocomplete-search', get_stylesheet_directory_uri(). '/assets/js/autocomplete.js', 
        ['jquery', 'jquery-ui-autocomplete'], null, true);
    wp_localize_script('autocomplete-search', 'AutocompleteSearch', [
        'ajax_url' => admin_url('admin-ajax.php'),
        'ajax_nonce' => wp_create_nonce('autocompleteSearchNonce')
    ]);
 
    $wp_scripts = wp_scripts();
    wp_enqueue_style('jquery-ui-css',
        '//ajax.googleapis.com/ajax/libs/jqueryui/'. $wp_scripts->registered['jquery-ui-autocomplete']->ver. '/themes/smoothness/jquery-ui.css',
        false, null, false
    );
});
 
add_action('wp_ajax_nopriv_autocompleteSearch', 'awp_autocomplete_search');
add_action('wp_ajax_autocompleteSearch', 'awp_autocomplete_search');
function awp_autocomplete_search() {
    check_ajax_referer('autocompleteSearchNonce', 'security');
 
    $search_term = $_REQUEST['term'];
    if (!isset($_REQUEST['term'])) {
        echo json_encode([]);
    }
 
    $suggestions = [];
    $query = new WP_Query([
        's' => $search_term,
        'posts_per_page' => -1,
    ]);
    if ($query->have_posts()) {
        while ($query->have_posts()) {
            $query->the_post();
            $suggestions[] = [
                'id' => get_the_ID(),
                'label' => get_the_title(),
                'link' => get_the_permalink()
            ];
        }
        wp_reset_postdata();
    }
    echo json_encode($suggestions);
    wp_die();
}

jQuery(function($) {
    $('.search-form .search-field').autocomplete({
        source: function(request, response) {
            $.ajax({
                dataType: 'json',
                url: AutocompleteSearch.ajax_url,
                data: {
                    term: request.term,
                    action: 'autocompleteSearch',
                    security: AutocompleteSearch.ajax_nonce,
                },
                success: function(data) {
                    response(data);
                }
            });
        },
        select: function(event, ui) {
            window.location.href = ui.item.link;
        },
    });
});