Como criar um modelo de pesquisa avançada personalizado no WordPress

Este guia é para você que tem um tipo de postagem personalizado (CPT) e deseja uma página de pesquisa avançada que pesquise resultados nesse CPT. No formulário de pesquisa, você pode configurar diferentes entradas para pesquisar em diferentes campos; título da postagem, conteúdo da postagem, qualquer tipo de meta personalizada ou por taxonomia personalizada.

Nesta postagem, vamos supor que temos um tipo de postagem personalizado para livros, uma taxonomia personalizada anexada para gênero de livro e um monte de meta personalizada; autor, ano de publicação, número ISBN e uma caixa de verificação se o livro está ou não em estoque. O tipo de postagem e os parâmetros personalizados são totalmente a seu critério para atender às suas necessidades, o código abaixo simplesmente tentará cobrir a maioria das bases.

O que vamos fazer

Criaremos um tipo de postagem personalizado para livros e uma taxonomia hierárquica personalizada anexada a ele para gênero. Além disso, cada livro tem campos personalizados para autor(es), ano de publicação, número ISBN e uma caixa de seleção para incluir ou não livros que estão esgotados. Quanto à página de pesquisa em si, faremos um modelo de página onde residirá a maior parte do nosso código. A página começará renderizando um formulário personalizado no início; mostrando todos os parâmetros possíveis para filtrar os resultados. Abaixo dele, todos os resultados do livro aparecerão em uma lista. Decidimos um número de resultados por página e adicionamos paginação na parte inferior se o número exceder isso.

Estes são os possíveis parâmetros de filtro que criaremos para nosso modelo de pesquisa avançada:

• Entrada de texto para pesquisar qualquer string no título do post e no conteúdo do post.
• Lista suspensa para escolher um gênero. Permite escolher um termo ou deixá-lo em “Qualquer".
• Entrada para digitar o nome do autor que pesquisa no meta personalizado. A correspondência livre, o que significa inserir "Marca", retornará todos os autores cujo nome seja ou contenha "Marca".
• Número de entrada para inserir o ano em que o livro foi publicado, que pesquisa no meta personalizado. A correspondência vaga, o que significa inserir, por exemplo, "20", corresponderá a qualquer livro publicado em 1920 ou em qualquer ano começando com 20.
• Entrada para inserir ISBN (ID internacional do livro) que pesquisa em meta personalizada. Retorna apenas correspondências precisas.
• Marque a caixa de seleção para incluir ou não livros esgotados, mais uma meta personalizada. Por padrão, isso está desmarcado, o que significa que os resultados mostram apenas os livros que estão em estoque.

O formulário está configurado para usar o método GET, o que significa que quaisquer parâmetros pesquisados ​​serão anexados à página na URL, na forma de ” ?book-search=world&year-published=2016&book-author=mark“. A outra opção se você quiser evitar ter “URLs feias” é usar Javascript e AJAX. Mas há algumas desvantagens com isso. Em primeiro lugar, não será possível marcar uma pesquisa com parâmetros de pesquisa específicos "pré-preenchidos". Imagine que você em outro lugar do seu site deseja vincular diretamente à sua página de pesquisa personalizada por um autor específico. Você pode então fazer o link ir para sua página de pesquisa, anexar ” ?author=mark“, e assim clicar no link levará diretamente aos resultados para esse autor. Isso não é possível com AJAX.

Os parâmetros de pesquisa são mutuamente inclusivos. Isso significa que combinar, por exemplo, o ano “2011” e o autor “Some guy” retornará apenas livros que correspondam a AMBOS. Se também especificarmos “engraçado” na entrada de texto de pesquisa geral, obteremos apenas retornos que correspondam a todos os três. Dito em palavras diferentes; usaremos a lógica AND. Este é o método mais comum para filtrar os resultados da pesquisa.

Este tutorial não incluirá estilo, então esta parte é com você. Abaixo está um exemplo de como isso pode ficar com alguns estilos básicos.

Uma observação sobre paginação com uma consulta personalizada

Se você deseja paginação em uma consulta personalizada em uma única página, há algumas coisas a serem observadas. A paginação de uma consulta pode ser gerada com as funções do WordPress [the_posts_pagination](https://developer.wordpress.org/reference/functions/the_posts_pagination/)(), [paginate_links](https://developer.wordpress.org/reference/functions/paginate_links/)(), ou os dois [next_post_link](https://developer.wordpress.org/reference/functions/next_post_link/)()e [previous_post_link](https://developer.wordpress.org/reference/functions/previous_post_link/)(). No entanto, eles são codificados para funcionar com o wp_queryobjeto global (que para um modelo de página é a própria página) e não com uma consulta personalizada.

Existem algumas soluções alternativas, como escrever você mesmo uma função de paginação. Ou você pode usar a ação pre_get_postse manipular o wp_queryobjeto. Infelizmente, este método é muito tarde para afetar as funções de paginação. Outra alternativa é pular a paginação e simplesmente mostrar todos os posts. Essa pode ser uma opção se você não tiver muitas postagens, mas se estiver criando um modelo de pesquisa personalizado avançado – suponho que você tenha algumas postagens.

O que faremos neste guia é uma espécie de método “hackish”. Dentro do modelo de página, substituiremos o wp_queryobjeto com nossa consulta personalizada para que as funções de loop e paginação funcionem conforme o esperado. Este método é o que eu tive mais sucesso.

Sem mais delongas, vamos começar a codificar!

Configurando o tipo de postagem personalizado, taxonomia e meta campos

A primeira etapa é definir o tipo de postagem personalizado para o qual queremos criar um modelo de pesquisa avançada. Se você já configurou um tipo de postagem personalizado ou deseja implementá-lo para postagens ou páginas, pode pular para a próxima parte.

Estamos definindo um tipo de postagem personalizado bookcom uma taxonomia personalizada hierárquica book_category. Não entrarei em detalhes explicando como criar tipos de postagem personalizados e taxonomias aqui. Se você estiver interessado em saber mais, tenho um post que entra em detalhes sobre isso.

Coloque este código em qualquer lugar no código do seu tema functions.phpou plugin:

Isso resultará em um tipo de postagem personalizado com uma taxonomia anexada a ele em admin.

A configuração da meta de postagem personalizada depende um pouco de você – manuseie-a manualmente [add_meta_box](https://developer.wordpress.org/reference/functions/add_meta_box/)()ou use o plug-in Advanced Custom Fields (ACF), que é perfeito para esse tipo de trabalho. Vou usar o ACF para configurar os campos programaticamente, assim:

É claro que você pode configurar os campos do ACF usando a GUI de administração do ACF. Mas há vários benefícios de adicioná-los por código. Por exemplo, garantindo que você mantenha os mesmos campos onde quer que você ative seu tema ou plugin. Se você configurar os campos no admin, lembre-se de exportá-los e importá-los se mudar de site WordPress.

Observe os meta-nomes; por exemplo book_author, year_published, e assim por diante. Você fará referência a eles quando criarmos a consulta personalizada no modelo de pesquisa avançada.

Com o plugin ACF e o código acima, editar um único livro ficaria assim:

Com isso estamos todos bem para criar quantos posts de livros quisermos. A próxima etapa é criar o modelo de página para nossa pesquisa.

Criando o modelo de página

Vamos criar o modelo de página onde colocaremos nosso modelo de pesquisa avançada. Faça uma cópia do seu tema single.phpou page.phpe renomeie-o para, por exemplo, template-booksearch.php. O HTML é com você, mas a razão pela qual fazemos uma cópia de single ou page é porque eles são provavelmente o modelo mais próximo em termos de layout.

No topo do modelo de página, indicamos que este é um modelo de página escrevendo "Nome do modelo" e seu nome no bloco de comentários. Fazer isso garantirá que possamos selecionar o modelo de página quando editarmos uma página.

As seções que precisamos codificar em nosso modelo são as seguintes, nesta ordem:

1. Armazene todas as variáveis ​​previamente enviadas pelo formulário, usando get_query_var(). Também precisa armazenar a página atual
2. Renderize o formulário de pesquisa com um botão de envio para realizar uma pesquisa
3. Redefinir o wp_queryobjeto
4. Configure os argumentos para um novo WP_Query()dependendo dos parâmetros pesquisados ​​e execute a consulta. Atribuir a consulta personalizada ao wp_queryobjeto
5. Percorra os resultados e exiba-os. Também renderizar links de paginação
6. Redefinir o wp_queryobjeto de volta ao que era

A razão pela qual precisamos armazenar todas as variáveis ​​pesquisadas e a página atual antecipadamente é porque essas variáveis ​​serão perdidas assim que redefinirmos o wp_queryobjeto na etapa 3. Também precisamos das variáveis ​​para nosso formulário de pesquisa, para preencher os campos.

Em seu modelo, decida o local em que deseja gerar sua pesquisa personalizada e vamos começar do início:

1 Obtenha todas as variáveis ​​pesquisadas

Obtemos os parâmetros GET (da URL) com [get_query_var](https://developer.wordpress.org/reference/functions/get_query_var/)(). Por exemplo; se tivermos um parâmetro ?book-author=benjaminna URL, using get_query_var('book-author')retornaria a string ‘ benjamin‘. A busca de todas as variáveis ​​pode ser feita assim:

$search_string = get_query_var('book-search');
$author = get_query_var('book-author');
$category = get_query_var('book-category');
$year = get_query_var('year-published');
$isbn = get_query_var('isbn');
$out_of_stock = get_query_var('out-of-stock');

Mas esses são todos os parâmetros personalizados que não fazem parte dos parâmetros GET padrão do WordPress. O WordPress irá ignorar quaisquer parâmetros GET que ele não conheça, então chamá-los sempre retornará uma string vazia. Precisamos dizer ao WordPress para permitir cada um desses parâmetros GET. Fazemos isso filtrando query_vars. No seu functions.php, adicione isso também:

add_filter('query_vars', function($vars) {
    $vars[] = 'book-search';
    $vars[] = 'book-author';
    $vars[] = 'book-category';
    $vars[] = 'year-published';
    $vars[] = 'isbn';
    $vars[] = 'out-of-stock';
    return $vars;
});

Agora nossos get_query_var()‘s devem ser capazes de buscar os parâmetros GET. Se eles não estiverem definidos, ele retornará uma string vazia.

Também precisamos buscar a página atual antes de estragar o wp_queryobjeto. A página atual é um parâmetro GET oculto chamado paged. Vamos buscá-lo da mesma forma que nossos outros parâmetros GET, mas vamos defini-lo como padrão para 1 se estiver vazio.

$paged = (get_query_var('paged'))? get_query_var('paged'): 1;

Nota: Como pagedé um parâmetro padrão do WordPress, não precisamos adicionar pagedao query_varsfiltro.

2 Renderize o formulário de pesquisa

O formulário de pesquisa será simplesmente um <form>com as entradas necessárias e um botão de envio de formulário. O HTML fica totalmente a seu critério, no exemplo abaixo estou adicionando as entradas em uma lista simples. Não incluirei nenhum estilo neste tutorial, isso é com você. Você pode optar por estilizar o formulário de pesquisa para ficar na parte superior dos resultados ou na lateral – verticalmente para baixo junto com os resultados da pesquisa.

Nota: Para encurtar e modularizar o modelo de pesquisa avançada, você pode separar a parte do formulário de pesquisa em um arquivo de modelo separado e incluí-lo com [get_template_part](https://developer.wordpress.org/reference/functions/get_template_part/)(). Mas para simplificar este tutorial, incluirei tudo dentro do próprio arquivo de modelo.

O formulário em si precisa ser do método GET, e a ação precisa apontar para a página em que estamos. Para fazer isso, acessamos o $postobjeto global e obtemos o permalink dele. No final, adicionamos um botão de envio que enviará o formulário.

Dentro da lista não ordenada, adicionaremos uma entrada adequada para cada um de nossos possíveis parâmetros de pesquisa. Ajuste o HTML e os parâmetros de pesquisa para atender às suas necessidades:

Observe os nameatributos; eles são o que aparecerá na URL quando o formulário for enviado. Eles devem corresponder ao query_varse get_query_var()definimos anteriormente!

O código acima começa renderizando uma entrada de texto para a pesquisa de texto geral. Definimos o valuepara a variável pesquisada anteriormente que buscamos usando get_query_var(). Isso garante que a entrada não seja limpa depois de fazermos uma pesquisa.

O próximo parâmetro é uma lista suspensa de gênero de nossa taxonomia personalizada. Para renderizar isso, utilizamos a função [wp_dropdown_categories](https://developer.wordpress.org/reference/functions/wp_dropdown_categories/)(). Dê uma olhada na página de documentação para ver por que adicionamos todos esses parâmetros para ajustar a lista suspensa às nossas necessidades. É importante que taxonomyesteja definido para nossa taxonomia personalizada, nameo atributo esteja correto e selecteddefinido para o valor da variável pesquisada anteriormente. Também definimos os valores de termo como seus slugs em vez de IDs de termo. Parece melhor com ?book-category=fictionem vez de ?book-category=42. Também ativamos uma opção “nenhum” para adicionar uma opção “Qualquer gênero”.

Em seguida, renderizamos outra entrada de texto para pesquisar o autor, uma entrada de número para o ano de publicação, uma entrada de texto para o número ISBN e, finalmente, uma caixa de seleção que, por padrão, está desmarcada para incluir livros esgotados.

3 Redefina o wp_query

O próximo passo é um pequeno hack para garantir que a paginação funcione para nossa consulta personalizada. Nós simplesmente armazenamos a corrente $wp_queryem alguma variável e então a configuramos para null. Mais tarde, na etapa 6, vamos redefini-lo a partir da $tmp_wpqueryvariável.

$tmp_wpquery = $wp_query;
$wp_query = null;

4 Configure argumentos e execute a consulta personalizada

Esta parte trata da realização de uma nova consulta. Começamos configurando os argumentos mais básicos e, em seguida, adicionamos parâmetros condicionalmente dependendo do que foi encontrado nas variáveis ​​pesquisadas anteriormente (de nossos get_query_var()s).

O código acima está basicamente construindo um WP_Querycom parâmetros. A página de documentação para WP_Queryé um ótimo recurso para descobrir como construir uma consulta.

Os primeiros argumentos garantem que consultamos apenas livros e que estamos informando corretamente em qual página estamos atualmente – a partir da pagedvariável que buscamos anteriormente. O número de posts por página fica a seu critério, eu simplesmente configurei para 20.

Observe que adicionar ‘ compare‘ a ‘ LIKE‘ fará com que o WordPress procure qualquer coisa que contenha a string fornecida. Não adicionei isso à pesquisa do ISBN porque, para esse campo, quero encontrar resultados que correspondam perfeitamente.

O importante é logo no final, quando realmente realizamos a consulta, e atribuímos essa consulta à wp_queryvariável.

5 Percorra os resultados da consulta e renderize a paginação

Este passo é realmente fácil. Tudo o que precisamos é de um loop padrão e, para cada um, renderizamos o post do livro como quisermos. Esta parte é totalmente com você.

O código abaixo mostra um exemplo básico de loop pelos resultados, chamando get_template_part()cada post. Depois que o loop the_posts_pagination()é usado para renderizar links de paginação. Se a consulta não retornou nenhuma postagem, um parágrafo simples com um texto será exibido.

Ajuste o HTML e a saída para atender às suas necessidades. O código acima espera um arquivo de modelo no tema nomeado content-book.phppara renderizar um único livro no loop. Não vou mostrar como renderizar cada postagem, pois isso é algo sobre o qual você provavelmente já tem controle.

6 Redefina o wp_query de volta ao que era

A etapa final é redefinir o wp_queryobjeto para o que armazenamos anteriormente na etapa 3. Definimos como nullprimeiro para garantir que seja redefinido.

$wp_query = null;
$wp_query = $tmp_wpquery;

Conclusão e resultado final

E foi isso! Agora você deve ter um modelo de pesquisa personalizada avançada totalmente funcional. Espero que isso tenha ajudado você – o código foi escrito o mais geral possível para facilitar o ajuste às suas necessidades. Talvez você queira diferentes tipos de parâmetros ou seu tipo de postagem personalizado seja para filmes ou outra coisa!

Com algum estilo básico, pode facilmente se parecer com isso:

Aqui está o código final; a functions.phppeça e o modelo: