Fazendo pesquisa de preenchimento automático no WordPress com código

Este tutorial é para você que deseja implementar uma pesquisa de preenchimento automático no WordPress, onde temos total controle das correspondências retornadas.

Aplicaremos um preenchimento automático à pesquisa padrão do WordPress, mas o código é altamente flexível para que você possa personalizar a consulta de acordo com suas necessidades. Seja uma consulta mais específica por um tipo de postagem personalizado, meta de postagem, categorias ou consultas em um tipo de conteúdo completamente diferente, como usuários ou algo manual do banco de dados. Você também pode aplicar facilmente o preenchimento automático em uma entrada de pesquisa personalizada em vez da pesquisa padrão do WordPress.

O que vamos fazer

O preenchimento automático é uma caixa de interface do usuário que aparece abaixo do campo de pesquisa mostrando as correspondências enquanto você digita. Ao clicar em uma correspondência, o navegador o enviará para o link permanente dessa postagem. Isso fornece ao usuário final uma maneira mais rápida de navegar em seu conteúdo, pois ele não precisará fazer o desvio extra para sua página de resultados de pesquisa. Usaremos AJAX para atualizar continuamente as correspondências enquanto o usuário digita.

O preenchimento automático é gerado com a ajuda do jQuery UI Autocomplete, um script incluído no WordPress como padrão.

Configurando o código

Você precisará adicionar o código no functions.phparquivo PHP do tema ou de um plugin ativo. Este tutorial é baseado em adicioná-lo em um tema. Ajuste os caminhos para se adequar ao seu projeto.

O primeiro passo é criar um arquivo Javascript que conterá nosso código para acionar o preenchimento automático. Quanto a este tutorial vou criar um arquivo vazio na pasta autocomplete.jsdo meu tema. assets/js/Onde você coloca seu arquivo fica a seu critério, apenas lembre-se de ajustar os caminhos abaixo. Voltaremos a esse arquivo depois de enfileirarmos esse arquivo corretamente no WordPress.

Enfileiramento de scripts e estilos

Precisamos enfileirar nosso arquivo Javascript de preenchimento automático e também precisamos nos certificar de enfileirar jQuery e jQuery UI Autocomplete. Além disso, o WordPress não inclui nenhum estilo para bibliotecas de interface do usuário do jQuery, portanto, também precisamos enfileirar uma folha de estilo para a interface do usuário do jQuery do Google CDN. Isso é opcional, claro. Você pode adicionar o CSS de outra forma ou talvez prefira estilizá-lo você mesmo.

Vamos enfileirar todos os scripts e estilos em uma função ligada 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);
});

A [wp_enqueue_script](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)()chamada de função acima adicionará nosso arquivo Javascript recém-criado com as dependências corretas (o array como terceiro parâmetro). Isso garante que o WordPress adicione os scripts jQuery e jQuery UI Autocomplete em nossa instância do WordPress.

Em seguida, precisamos fornecer algumas variáveis ​​que podemos acessar em nosso script de preenchimento automático. Precisamos saber o URL AJAX e também queremos adicionar um nonce para segurança. Podemos fazer isso 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')
    ]);
});

A wp_localize_script()função criará uma variável Javascript global AutocompleteSearchcom duas propriedades; ajax_urle ajax_nonce. Com isso, podemos em nosso arquivo Javascript autocompletar buscar, por exemplo, o valor da URL AJAX do WordPress com AutocompleteSearch.ajax_url.

Finalmente, precisamos adicionar algum estilo. Como mencionado, o WordPress não vem com nenhum estilo de interface do usuário jQuery incluído, portanto, precisamos adicionar alguns nós mesmos. Optei por adicionar uma folha de estilo via Google CDN. Mas precisamos saber o número da versão da interface do usuário do jQuery para buscar sua folha de estilo. Poderíamos codificar um número de versão, mas não sou fã de codificar nada. Abaixo, você encontrará um bom truque para aproveitar as informações da versão do jQuery UI armazenadas no 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 e adicionar uma nova folha de estilo com o caminho CDN fornecido como segundo argumento. Para buscar um número de versão de UI do jQuery válido, usamos as informações fornecidas pela função [wp_scripts](https://developer.wordpress.org/reference/functions/wp_scripts/)().

E isso é tudo que precisamos para enfileirar scripts!

Escrevendo o Javascript de preenchimento automático

Vamos voltar ao nosso autocomplete.jsarquivo. Sabemos que quando este script é carregado, jQuery e jQuery UI Autocomplete já estão carregados, e também temos acesso a uma variável global com as informações necessárias. Vamos começar configurando uma função pronta de documento jQuery para garantir que nosso código seja executado depois que o DOM estiver pronto.

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

Se nos referirmos à documentação do jQuery UI Autocomplete, aprendemos que precisamos fazer um seletor jQuery visando um campo de entrada e executar a função autocomplete()nele.

Este é um ponto em que você pode ajustar o código para atender às suas necessidades. Este tutorial aplicará o preenchimento automático no campo de pesquisa padrão do WordPress (que geralmente é adicionado ao tema, incluindo o modelo de pesquisa ou como um widget). Os nomes de classe da entrada de pesquisa podem variar de tema para tema. Mas talvez você queira segmentar um campo de entrada personalizado ou pesquisar em um modelo especial. Tudo o que você precisa fazer é alterar o seletor jQuery para direcionar a entrada desejada.

No meu tema, a entrada padrão do campo de pesquisa do WordPress tem uma classe de .search-field. Também estou adicionando o nome da classe do formulário pai para reduzi-lo ainda mais, para não corrermos o risco de o preenchimento automático ser aplicado a outra coisa usando a mesma classe.

De acordo com a documentação do Autocomplete podemos realizar uma chamada AJAX na propriedade source(que deve retornar um array de itens para exibir no autocomplete). Usaremos a função Ajax do jQuery para fazer exatamente isso:

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

Na linha #2é onde informamos ao jQuery UI Autocomplete em qual campo de entrada queremos aplicar o autocomplete. Altere este seletor para atender às suas necessidades.

Na forma mais simples, o Autocomplete espera uma matriz de objetos de item para a sourcepropriedade. Aqui criamos uma função com dois parâmetros; requestcontém informações sobre nosso valor inserido (request.term), e responsequal é uma função de retorno de chamada que precisamos chamar e fornecer os dados. Isso é o que fazemos na successfunção do AJAX na linha #13.

A própria chamada AJAX é bastante padrão. Definimos o tipo de dados como JSON – isso é importante, caso contrário o jQuery UI Autocomplete não poderá analisar os resultados. À medida urlque acessamos ajax_urla variável global, localizamos nosso script anteriormente; AutocompleteSearch. E como datapassamos um objeto de informação. A actionpropriedade é obrigatória e necessária para a próxima etapa – que é identificar essa solicitação AJAX específica no PHP. Também passamos o termo inserido na entrada e o nonce para fins de segurança.

Isso é tudo para a sourcespropriedade. Há uma outra coisa que precisamos adicionar em nosso script de preenchimento automático. Como padrão no jQuery UI Autocomplete escolher um item simplesmente preenche automaticamente a entrada com o elemento escolhido. Queremos redirecionar o usuário para a URL da postagem ao escolher um item da lista. Então, adicionamos uma função à selectpropriedade:

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

No array de itens que retornaremos de nossa chamada AJAX (escreveremos isso a seguir) cada item é um objeto com propriedades. Adicionaremos uma linkpropriedade personalizada a cada item (ui.item) que conterá os links permanentes para cada postagem. Passamos este URL para [window.location.href](https://www.w3schools.com/js/js_window_location.asp)o qual acionará um redirecionamento do navegador.

E isso é tudo para a parte de Javascript! Tudo o que resta é escrever a parte PHP que escuta as solicitações AJAX com a ação autocompleteSearch.

Retornando resultados em solicitações PHP para AJAX

Para escrever funções que respondem a solicitações AJAX específicas, usamos os ganchos wp_ajax_{action}(visitantes logados) e wp_ajax_nopriv_{action}(visitantes não logados). Definimos a ação como autocompleteSearchem nossa solicitação AJAX acima. Consulte o meu post que explica como o AJAX funciona no WordPress se você não estiver familiarizado com isso.

Vamos configurar isso em functions.php(ou em qualquer lugar em PHP que você adicione seu código):

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

Com o código acima, conectamos a mesma função aos dois ganchos AJAX. Em todas as funções que são conectadas aos ganchos wp_ajax AJAX, devemos ter certeza de sempre die()ou exitno final para não ecoar uma saída indesejada. Estou usando a [wp_die](https://developer.wordpress.org/reference/functions/wp_die/)()função do WordPress.

Podemos buscar os dados passados ​​do Javascript usando $_REQUEST(funciona para solicitações GET e POST). Em nosso código Javascript passamos o termo inserido na chave ‘ term‘. Isso significa que podemos buscar o valor dele em $_REQUEST['term']. Podemos então realizar uma consulta com base nisso. Lembre-se de que queremos retornar apenas resultados que correspondam a esse termo de pesquisa.

Este é outro ponto em que você pode alterar e ajustar totalmente o código para atender às suas necessidades. Este tutorial realizará uma consulta padrão em postagens e páginas, mas você pode ajustar a consulta ou realizar uma consulta completamente diferente em dados diferentes. Talvez você prefira ou precise executar uma consulta SQL manual (certamente é mais eficiente em termos de memória). A parte crucial aqui é a matriz que ecoamos no final, que é analisada pelo código de preenchimento automático do nosso 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();
}

Primeiro verificamos se o nonce era válido para estabelecer alguma segurança em nossas chamadas AJAX. Podemos fazer isso chamando a função [check_ajax_referer](https://developer.wordpress.org/reference/functions/check_ajax_referer/)(). Também adicionei código para garantir que não realizamos uma solicitação pesada se o termo de pesquisa retornado estiver vazio. Devemos então retornar um array codificado em json vazio.

O código de exemplo acima realiza [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/)uma pesquisa no termo inserido. Precisamos definir posts_per_pagecomo -1garantir o retorno de todas as partidas. Confira a documentação WP_Queryse quiser ajustar ainda mais a consulta.

Em seguida, percorremos os resultados (line #17) e preenchemos um array com correspondências (line #19-23). jQuery UI Autocomplete precisa, no mínimo, da propriedade labelpara significar o que deve ser exibido na caixa de autocomplete. Também passamos permalinks na chave ‘ link‘ que é o que usamos em nosso código Javascript para redirecionar o usuário.

Finalmente, na linha #27, ecoamos o array gerado como JSON usando [json_encode](https://www.php.net/manual/en/function.json-encode.php)().

Com essa parte do PHP instalada, nosso preenchimento automático deve funcionar! Atualize seu site e experimente!

Melhorias opcionais

Um problema comum é que o número de correspondências é muito grande e a caixa de preenchimento automático fica muito grande. Existem duas soluções para isso.

Uma solução é adicionar a propriedade minLengthà autocomplete()função em Javascript. Esta propriedade só acionará a caixa de autocompletar após a entrada de um certo número de caracteres. Como exemplo, podemos exigir um mínimo de 3 caracteres antes de acionar o preenchimento automático:

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

jQuery UI Autocomplete propõe outra solução aqui. Ele mostra um exemplo de adição de um pouco de CSS para adicionar uma altura fixa e uma barra de rolagem interna na caixa de preenchimento automático.

Conclusão e código completo

Adicionamos com sucesso um preenchimento automático à funcionalidade de pesquisa do WordPress, onde temos controle total das correspondências a serem retornadas. Isso oferece aos visitantes uma maneira mais rápida de navegar em seu conteúdo, pois clicar em uma correspondência redirecionará diretamente para a postagem, em vez de fazer um desvio em uma página de resultados de pesquisa primeiro. Implementar um preenchimento automático nem sempre faz sentido em todos os sites WordPress, mas pode ser ótimo para pesquisar conteúdo específico ou em modelos especiais!

Aqui está o código final na íntegra:

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