Hacer una búsqueda de Autocompletar en WordPress con código

Este tutorial es para usted que desea implementar una búsqueda de autocompletar en WordPress, donde tenemos el control total de las coincidencias devueltas.

Aplicaremos un autocompletado a la búsqueda estándar de WordPress, pero el código es muy flexible para que pueda personalizar la consulta según sus necesidades. Ya sea una consulta más específica por un tipo de publicación personalizada, publicación meta, categorías o consultas sobre un tipo de contenido completamente diferente, como usuarios o algo manual de la base de datos. También puede aplicar fácilmente el autocompletado en una entrada de búsqueda personalizada en lugar de la búsqueda estándar de WordPress.

que haremos

Autocompletar es un cuadro de interfaz de usuario que aparece debajo del campo de búsqueda y muestra las coincidencias mientras escribe. Al hacer clic en una coincidencia, el navegador lo enviará al enlace permanente de esa publicación. Esto proporciona al usuario final una forma más rápida de navegar por su contenido, ya que no necesitará tomar un desvío adicional a su página de resultados de búsqueda. Usaremos AJAX para actualizar continuamente las coincidencias mientras el usuario escribe.

El autocompletado se genera con la ayuda de jQuery UI Autocompletar, un script que se incluye en WordPress por defecto.

Configurando el código

Deberá agregar el código en el functions.phparchivo PHP del tema o en un complemento activo. Este tutorial se basa en agregarlo en un tema. Ajuste las rutas para que se ajusten a su proyecto.

El primer paso es crear un archivo Javascript que contendrá nuestro código para activar el autocompletado. En cuanto a este tutorial, crearé un autocomplete.jsarchivo vacío en la carpeta de mi tema assets/js/. El lugar donde coloque su archivo depende de usted, solo recuerde ajustar las rutas a continuación. Volveremos a este archivo después de haberlo puesto en cola correctamente en WordPress.

Encolar scripts y estilos

Necesitamos poner en cola nuestro archivo Javascript de autocompletar y también debemos asegurarnos de poner en cola jQuery y jQuery UI Autocompletar. Además, WordPress no incluye ningún estilo para las bibliotecas de jQuery UI, por lo que también debemos poner en cola una hoja de estilo para jQuery UI de Google CDN. Esto es opcional, por supuesto. Puede agregar el CSS de alguna otra manera o tal vez prefiera diseñarlo usted mismo.

Pondremos en cola todos los scripts y estilos en una función vinculada 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/)()llamada a la función anterior agregará nuestro archivo Javascript recién creado con las dependencias correctas (la matriz como tercer parámetro). Esto asegura que WordPress agregue los scripts jQuery y jQuery UI Autocompletar en nuestra instancia de WordPress.

A continuación, debemos proporcionar algunas variables a las que podemos acceder desde nuestro script de autocompletar. Necesitamos saber la URL de AJAX y también queremos agregar un nonce por seguridad. Podemos hacer esto 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()función creará una variable Javascript global AutocompleteSearchcon dos propiedades; ajax_urly ajax_nonce. Con esto podemos, en nuestro archivo Javascript de autocompletar, obtener, por ejemplo, el valor de la URL AJAX de WordPress con AutocompleteSearch.ajax_url.

Finalmente, necesitamos agregar algo de estilo. Como se mencionó, WordPress no viene con ningún estilo jQuery UI incluido, por lo que debemos agregar algunos nosotros mismos. Opté por agregar una hoja de estilo a través de Google CDN. Pero necesitamos saber el número de versión de jQuery UI para obtener su hoja de estilo. Podríamos codificar un número de versión, pero no soy partidario de codificar nada. A continuación, encontrará un buen truco para aprovechar la información de la versión de jQuery UI almacenada en 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
    );
});

Usamos [wp_enqueue_style](https://developer.wordpress.org/reference/functions/wp_enqueue_style/)()para registrar y agregar una nueva hoja de estilo con la ruta CDN proporcionada como segundo argumento. Para obtener un número de versión de jQuery UI válido, usamos la información proporcionada por la función [wp_scripts](https://developer.wordpress.org/reference/functions/wp_scripts/)().

¡Y eso es todo lo que necesitamos para poner en cola los scripts!

Escribiendo el Javascript de autocompletar

Volvamos a nuestro autocomplete.jsarchivo. Sabemos que cuando se carga este script, jQuery y jQuery UI Autocompletar ya están cargados, y también tenemos acceso a una variable global con la información necesaria. Comencemos configurando una función lista para documentos jQuery para garantizar que nuestro código se ejecute después de que DOM esté listo.

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

Si nos referimos a la documentación de jQuery UI Autocompletar, aprendemos que necesitamos hacer un selector de jQuery dirigido a un campo de entrada y ejecutar la función autocomplete()en él.

Este es un punto en el que puede modificar el código para que se ajuste a sus necesidades. Este tutorial aplicará el autocompletado en el campo de búsqueda estándar de WordPress (que generalmente se agrega en el tema al incluir la plantilla de búsqueda o como un widget). Los nombres de clase de la entrada de búsqueda pueden variar de un tema a otro. Pero es posible que desee apuntar a un campo de entrada personalizado o buscar dentro de una plantilla especial. Todo lo que necesita hacer es cambiar el selector de jQuery para apuntar a la entrada que desea.

En mi tema, la entrada del campo de búsqueda estándar de WordPress tiene una clase de .search-field. También estoy agregando el nombre de la clase del formulario principal para reducirlo aún más, de modo que no corramos el riesgo de que se aplique el autocompletado a otra cosa que use la misma clase.

De acuerdo con la documentación de Autocompletar, podemos realizar una llamada AJAX en la propiedad source(que debe devolver una matriz de elementos para mostrar en la función de autocompletar). Usaremos la función Ajax de jQuery para hacer precisamente eso:

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

En la línea #2es donde le decimos a jQuery UI Autocompletar en qué campo de entrada queremos aplicar la función de autocompletar. Cambie este selector para que se ajuste a sus necesidades.

En la forma más simple, Autocompletar espera una matriz de objetos de elementos para la sourcepropiedad. Aquí creamos una función con dos parámetros; requestcontiene información sobre nuestro valor ingresado (request.term), y responsecuál es una función de devolución de llamada que debemos llamar y proporcionar los datos. Eso es lo que hacemos en la successfunción de AJAX en la línea #13.

La llamada AJAX en sí es bastante estándar. Definimos el tipo de datos como JSON; esto es importante, de lo contrario jQuery UI Autocompletar no podrá analizar los resultados. A medida urlque accedemos ajax_urla la variable global que localizamos en nuestro script anteriormente; AutocompleteSearch. Y como datapasamos un objeto de información. La actionpropiedad es obligatoria y necesaria para el siguiente paso, que es identificar esta solicitud específica de AJAX en PHP. También pasamos el término ingresado en la entrada y el nonce por motivos de seguridad.

Eso es todo por la sourcespropiedad. Hay otra cosa que debemos agregar en nuestro script de autocompletar. De forma predeterminada en jQuery UI Autocompletar, al elegir un elemento, simplemente se autocompleta la entrada con el elemento elegido. Queremos redirigir al usuario a la URL de la publicación al elegir un elemento de la lista. Entonces agregamos una función a la selectpropiedad:

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

En la matriz de elementos que devolveremos de nuestra llamada AJAX (lo escribiremos a continuación), cada elemento es un objeto con propiedades. Agregaremos una linkpropiedad personalizada a cada elemento (ui.item) que contendrá los enlaces permanentes a cada publicación. Pasamos esta URL a [window.location.href](https://www.w3schools.com/js/js_window_location.asp)la que se activará una redirección del navegador.

¡Y eso es todo por la parte de Javascript! Todo lo que queda es escribir la parte de PHP que escucha las solicitudes de AJAX con la acción autocompleteSearch.

Devolviendo resultados en PHP a solicitudes AJAX

Para escribir funciones que respondan a solicitudes específicas de AJAX, usamos los ganchos wp_ajax_{action}(visitantes registrados) y wp_ajax_nopriv_{action}(visitantes no registrados). Definimos la acción como autocompleteSearchen nuestra solicitud AJAX anterior. Consulte mi publicación que explica cómo funciona AJAX en WordPress si no está familiarizado con esto.

Configuremos esto en functions.php(o donde sea que agregue su código en PHP):

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 el código anterior, enganchamos la misma función a los dos ganchos AJAX. En todas las funciones que están enganchadas a los ganchos wp_ajax AJAX, debemos asegurarnos de hacerlo siempre die()o exital final para no generar un eco de salida no deseado. Estoy usando la [wp_die](https://developer.wordpress.org/reference/functions/wp_die/)()función de WordPress.

Podemos obtener los datos pasados ​​​​de Javascript usando $_REQUEST(funciona para solicitudes GET y POST). En nuestro código Javascript pasamos el término ingresado en la clave ‘ term‘. Esto significa que podemos obtener su valor en $_REQUEST['term']. Entonces podemos realizar una consulta basada en esto. Recuerde que solo queremos devolver resultados que coincidan con este término de búsqueda.

Este es otro punto en el que puede cambiar y modificar completamente el código para que se ajuste a sus necesidades. Este tutorial realizará una consulta estándar en publicaciones y páginas, pero puede modificar la consulta o realizar una consulta completamente diferente en datos diferentes. Quizás prefiera o necesite realizar una consulta SQL manual en su lugar (ciertamente es más eficiente en memoria). La parte crucial aquí es la matriz que hacemos eco al final, que es analizada por el código de autocompletar de nuestro 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();
}

Primero verificamos si el nonce era válido para establecer cierta seguridad en nuestras llamadas AJAX. Podemos hacer esto llamando a la función [check_ajax_referer](https://developer.wordpress.org/reference/functions/check_ajax_referer/)(). También agregué código para garantizar que no realicemos una solicitud pesada si el término de búsqueda devuelto estaba vacío. Luego deberíamos devolver una matriz codificada en json vacía.

El código de ejemplo anterior realiza [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)una búsqueda en el término ingresado. Necesitamos establecer posts_per_pagecomo -1para asegurarnos de devolver todos los partidos. Consulte la documentación WP_Querysi desea modificar aún más la consulta.

Luego recorremos los resultados (línea #17) y completamos una matriz con coincidencias (línea #19-23). jQuery UI Autocompletar necesita como mínimo la propiedad labelpara indicar lo que debe mostrarse en el cuadro de autocompletar. También pasamos enlaces permanentes en la clave ‘ link‘ que es lo que usamos en nuestro código Javascript para redirigir al usuario.

Finalmente, en la línea #27, hacemos eco de la matriz generada como JSON usando [json_encode](https://www.php.net/manual/en/function.json-encode.php)().

Con esta parte de PHP en su lugar, nuestro autocompletado debería funcionar. ¡Actualiza tu sitio y pruébalo!

Mejoras opcionales

Un problema común es que la cantidad de coincidencias es demasiada y el cuadro de autocompletar se vuelve demasiado grande. Hay dos soluciones para esto.

Una solución es agregar la propiedad minLengtha la autocomplete()función en Javascript. Esta propiedad solo activará el cuadro de autocompletar después de que se haya ingresado una cierta cantidad de caracteres. Como ejemplo, podemos requerir un mínimo de 3 caracteres antes de activar la función de autocompletar:

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

jQuery UI Autocompletar propone aquí otra solución. Muestra un ejemplo de cómo agregar un poco de CSS para agregar una altura fija y una barra de desplazamiento interna en el cuadro de autocompletar.

Conclusión y código completo.

Hemos agregado con éxito una función de autocompletar a la función de búsqueda de WordPress donde tenemos control total de las coincidencias para devolver. Brinda a los visitantes una forma más rápida de navegar por su contenido, ya que al hacer clic en una coincidencia se redirigirá directamente a la publicación, en lugar de desviarse primero en una página de resultados de búsqueda. Es posible que implementar un autocompletado no siempre tenga sentido en todos los sitios de WordPress, ¡pero puede ser excelente para buscar contenido específico o dentro de plantillas especiales!

Aquí está el código final en su totalidad:

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