Effettuare la ricerca di completamento automatico in WordPress con il codice

Questo tutorial è per te che desideri implementare una ricerca di completamento automatico in WordPress, dove abbiamo il pieno controllo delle corrispondenze restituite.

Applicheremo un completamento automatico alla ricerca standard di WordPress, ma il codice è altamente flessibile in modo da poter personalizzare la query in base alle tue esigenze. Che si tratti di una query più specifica da parte di un tipo di post personalizzato, meta di post, categorie o query su un tipo di contenuto completamente diverso come utenti o qualcosa di manuale dal database. Puoi anche applicare facilmente il completamento automatico su un input di ricerca personalizzato invece della ricerca standard di WordPress.

Cosa faremo

Il completamento automatico è una casella dell’interfaccia utente che appare sotto il campo di ricerca che mostra le corrispondenze durante la digitazione. Dopo aver fatto clic su una corrispondenza, il browser ti invierà al permalink di quel post. Ciò fornisce all’utente finale un modo più veloce per navigare tra i tuoi contenuti poiché non avrà bisogno di fare una deviazione aggiuntiva alla tua pagina dei risultati di ricerca. Useremo AJAX per aggiornare continuamente le partite mentre l’utente digita.

Il completamento automatico viene generato con l’aiuto di jQuery UI Autocomplete, uno script incluso in WordPress come predefinito.

Impostazione del codice

Dovrai aggiungere il codice nel functions.phpfile PHP del tema o in un plugin attivo. Questo tutorial si basa sull’aggiunta in un tema. Regola i percorsi per adattarli al tuo progetto.

Il primo passo è creare un file Javascript che conterrà il nostro codice per attivare il completamento automatico. Per quanto riguarda questo tutorial creerò un autocomplete.jsfile vuoto nella cartella del mio tema assets/js/. Dove posizionare il file dipende da te, ricordati solo di regolare i percorsi di seguito. Torneremo su questo file dopo aver accodato correttamente questo file in WordPress.

Accodamento di script e stili

Dobbiamo accodare il nostro file Javascript di completamento automatico e dobbiamo anche assicurarci di accodare jQuery e jQuery UI Autocomplete. Inoltre, WordPress non include alcuno stile per le librerie dell’interfaccia utente jQuery, quindi è necessario anche accodare un foglio di stile per l’interfaccia utente jQuery da Google CDN. Questo è ovviamente facoltativo. Puoi aggiungere il CSS in un altro modo o forse preferisci personalizzarlo tu stesso.

Metteremo in coda tutti gli script e gli stili in una funzione collegata a 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);
});

La [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)()chiamata alla funzione sopra aggiungerà il nostro file Javascript appena creato con le dipendenze corrette (l’array come terzo parametro). Ciò garantisce che WordPress aggiunga gli script di completamento automatico dell’interfaccia utente jQuery e jQuery nella nostra istanza di WordPress.

Successivamente dobbiamo fornire alcune variabili a cui possiamo accedere dal nostro script di completamento automatico. Abbiamo bisogno di conoscere l’URL AJAX e vogliamo anche aggiungere un nonce per sicurezza. Possiamo farlo usando [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()funzione creerà una variabile Javascript globale AutocompleteSearchcon due proprietà; ajax_urle ajax_nonce. Con questo possiamo nel nostro file Javascript di completamento automatico recuperare ad esempio il valore dell’URL AJAX di WordPress con AutocompleteSearch.ajax_url.

Infine dobbiamo aggiungere un po’ di stile. Come accennato, WordPress non viene fornito con alcuno stile dell’interfaccia utente jQuery incluso, quindi dobbiamo aggiungerne alcuni noi stessi. Ho optato per l’aggiunta di un foglio di stile tramite Google CDN. Ma dobbiamo conoscere il numero di versione dell’interfaccia utente di jQuery per recuperare il suo foglio di stile. Potremmo codificare un numero di versione, ma non sono un fan dell’hardcoding. Di seguito troverai un bel trucco per anticipare le informazioni sulla versione dell’interfaccia utente di jQuery memorizzate in 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
    );
});

Usiamo [wp_enqueue_style](https://developer.wordpress.org/reference/functions/wp_enqueue_style/)()per registrare e aggiungere un nuovo foglio di stile con il percorso CDN fornito come secondo argomento. Per recuperare un numero di versione dell’interfaccia utente jQuery valido, utilizziamo le informazioni fornite dalla funzione [wp_scripts](https://developer.wordpress.org/reference/functions/wp_scripts/)().

E questo è tutto ciò di cui abbiamo bisogno per accodare gli script!

Scrivere il Javascript di completamento automatico

Torniamo al nostro autocomplete.jsfascicolo. Sappiamo che quando questo script viene caricato, jQuery e jQuery UI Autocomplete sono già caricati e abbiamo anche accesso a una variabile globale con le informazioni necessarie. Iniziamo impostando una funzione di pronto del documento jQuery per garantire che il nostro codice venga eseguito dopo che DOM è pronto.

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

Se ci riferiamo alla documentazione di jQuery UI Autocomplete, apprendiamo che è necessario creare un selettore jQuery mirato a un campo di input ed eseguire la funzione autocomplete()su di esso.

Questo è un punto in cui puoi modificare il codice per adattarlo alle tue esigenze. Questo tutorial applicherà il completamento automatico al campo di ricerca standard di WordPress (che di solito viene aggiunto nel tema includendo il modello di ricerca o come widget). I nomi delle classi dell’input di ricerca possono variare da tema a tema. Ma potresti voler scegliere come target un campo di input personalizzato o cercare all’interno di un modello speciale. Tutto quello che devi fare è cambiare il selettore jQuery per indirizzare l’input desiderato.

Nel mio tema l’input standard del campo di ricerca di WordPress ha una classe di .search-field. Sto anche aggiungendo il nome della classe del modulo padre per restringerlo ulteriormente in modo da non rischiare che il completamento automatico venga applicato a qualcos’altro utilizzando la stessa classe.

Secondo la documentazione del completamento automatico, possiamo eseguire una chiamata AJAX nella proprietà source(che deve restituire un array di elementi da visualizzare nel completamento automatico). Useremo la funzione Ajax di jQuery per fare proprio questo:

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

Alla riga #2è dove diciamo a jQuery UI Autocomplete su quale campo di input vogliamo applicare il completamento automatico. Modifica questo selettore in base alle tue esigenze.

Nella forma più semplice, il completamento automatico prevede una matrice di oggetti oggetto nella sourceproprietà. Qui creiamo una funzione con due parametri; requestcontiene informazioni sul nostro valore immesso (request.term) e responsequale è una funzione di callback che dobbiamo chiamare e fornire i dati. Questo è ciò che facciamo nella successfunzione di AJAX alla riga #13.

La stessa chiamata AJAX è piuttosto standard. Definiamo il tipo di dati come JSON: questo è importante, altrimenti il ​​completamento automatico dell’interfaccia utente di jQuery non sarà in grado di analizzare i risultati. Quando urlaccediamo ajax_urlalla variabile globale, abbiamo localizzato il nostro script in precedenza; AutocompleteSearch. E mentre datapassiamo un oggetto di informazione. La actionproprietà è obbligatoria e necessaria per il passaggio successivo, che identifica questa specifica richiesta AJAX in PHP. Trasmettiamo anche il termine immesso nell’input e il nonce per motivi di sicurezza.

Questo è tutto per la sourcesproprietà. C’è un’altra cosa che dobbiamo aggiungere nel nostro script di completamento automatico. Come predefinito nell’interfaccia utente di jQuery, il completamento automatico, la scelta di un elemento riempie automaticamente l’input con l’elemento scelto. Vogliamo reindirizzare l’utente all’URL del post quando sceglie un elemento dall’elenco. Quindi aggiungiamo una funzione alla selectproprietà:

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

Nell’array di elementi che ritorneremo dalla nostra chiamata AJAX (lo scriveremo in seguito) ogni elemento è un oggetto con proprietà. Aggiungeremo una linkproprietà personalizzata a ciascun elemento (ui.item) che conterrà i permalink a ciascun post. Passiamo questo URL a [window.location.href](https://www.w3schools.com/js/js_window_location.asp)cui attiverà un reindirizzamento del browser.

E questo è tutto per la parte Javascript! Non resta che scrivere la parte PHP che ascolta le richieste AJAX con l’azione autocompleteSearch.

Restituzione dei risultati in PHP alle richieste AJAX

Per scrivere funzioni che rispondano a specifiche richieste AJAX utilizziamo gli hook wp_ajax_{action}(visitatori registrati) e wp_ajax_nopriv_{action}(visitatori non registrati). Abbiamo definito l’azione come autocompleteSearchnella nostra richiesta AJAX sopra. Fai riferimento al mio post che spiega come funziona AJAX in WordPress se non hai familiarità con questo.

Installiamolo in functions.php(o ovunque in PHP aggiungi il tuo codice):

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

Con il codice precedente agganciamo la stessa funzione ai due hook AJAX. In tutte le funzioni che sono agganciate agli hook AJAX wp_ajax, dobbiamo assicurarci di farlo sempre die()o exitalla fine in modo da non echeggiare l’output indesiderato. Sto usando la [wp_die](https://developer.wordpress.org/reference/functions/wp_die/)()funzione di WordPress.

Possiamo recuperare i dati passati da Javascript usando $_REQUEST(funziona sia per le richieste GET che POST). Nel nostro codice Javascript abbiamo passato il termine inserito nella chiave ‘ term‘. Ciò significa che possiamo recuperarne il valore in $_REQUEST['term']. Possiamo quindi eseguire una query basata su questo. Ricorda che vogliamo solo restituire risultati che corrispondono a questo termine di ricerca.

Questo è un altro punto in cui puoi cambiare completamente e modificare il codice per adattarlo alle tue esigenze. Questo tutorial eseguirà una query standard su post e pagine, ma puoi modificare la query o eseguire una query completamente diversa su dati diversi. Forse preferisci o devi eseguire invece una query SQL manuale (è sicuramente più efficiente in termini di memoria). La parte cruciale qui è l’array che echeggiamo alla fine, che viene analizzato dal codice di completamento automatico del nostro 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();
}

Per prima cosa controlliamo se il nonce era valido per stabilire una certa sicurezza sulle nostre chiamate AJAX. Possiamo farlo chiamando la funzione [check_ajax_referer](https://developer.wordpress.org/reference/functions/check_ajax_referer/)(). Ho anche aggiunto del codice per assicurarci di non eseguire una richiesta pesante se il termine di ricerca restituito era vuoto. Dovremmo quindi restituire un array con codifica json vuoto.

Il codice di esempio sopra esegue [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)una ricerca sul termine immesso. Dobbiamo fare in posts_per_pagemodo -1di assicurarci di restituire tutte le partite. Consulta la documentazione per WP_Querymodificare ulteriormente la query.

Quindi eseguiamo il ciclo dei risultati (line #17) e popolano un array con corrispondenze (line #19-23). Il completamento automatico dell’interfaccia utente di jQuery richiede come minimo la proprietà labelper indicare ciò che dovrebbe essere visualizzato nella casella di completamento automatico. Trasmettiamo anche i permalink nella chiave ‘ link‘ che è ciò che usiamo nel nostro codice Javascript per reindirizzare l’utente.

Infine in linea #27facciamo eco all’array generato come JSON usando [json_encode](https://www.php.net/manual/en/function.json-encode.php)().

Con questa parte PHP attiva, il nostro completamento automatico dovrebbe funzionare! Aggiorna il tuo sito e provalo!

Miglioramenti opzionali

Un problema comune è che il numero di corrispondenze è eccessivo e la casella di completamento automatico diventa troppo grande. Ci sono due soluzioni a questo.

Una soluzione è aggiungere la proprietà minLengthalla autocomplete()funzione in Javascript. Questa proprietà attiverà la casella di completamento automatico solo dopo che è stato inserito un certo numero di caratteri. Ad esempio, possiamo richiedere un minimo di 3 caratteri prima di attivare il completamento automatico:

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

jQuery UI Autocomplete propone qui un’altra soluzione. Mostra un esempio di aggiunta di un po’ di CSS per aggiungere un’altezza fissa e una barra di scorrimento interna nella casella di completamento automatico.

Conclusione e codice completo

Abbiamo aggiunto con successo un completamento automatico alla funzionalità di ricerca di WordPress in cui abbiamo il pieno controllo delle corrispondenze da restituire. Offre ai visitatori un modo più rapido per navigare tra i tuoi contenuti poiché facendo clic su una corrispondenza si reindirizzerà direttamente al post, piuttosto che fare prima una deviazione in una pagina dei risultati di ricerca. L’implementazione di un completamento automatico potrebbe non avere sempre senso in tutti i siti WordPress, ma può essere ottimo per la ricerca di contenuti specifici o all’interno di modelli speciali!

Ecco il codice finale nella sua interezza:

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