22 set

Customizando a query do WordPress

Categoria: - Comentários (14)

Um dos mais poderosos recursos do WordPress é a WP Query. É ela que determina qual conteúdo será exibido e em qual página ou template. É muito provável que você precise (ou já precisou) modificar esta query para atender às suas necessidades.

Alguns exemplos:

  • Para não mostrar posts de uma categoria X na home do seu site
  • Aumentar ou diminuir o número de posts por página de um post type específico
  • Determinar quais posts são exibidos e ordenar baseando-se em uma post meta
  • Dentro de uma página, fazer uma query diferente para obter diferentes conteúdos

Antes de tudo, conheça os tipos de Loop

Há dois contextos diferentes para loops:

  • Principal (main loop) – É o loop baseado numa requisição via URL e processada antes que os templates são carregados.
  • Secundários (secondary loop) – São loops que ocorrem de qualquer outra maneira, chamados de arquivos do template ou de outra forma.

Não use query_posts() para alterar o loop principal. Como pode ser visto no Codex, há um monte de advertências sobre o uso desta função, use a classe WP_Query() ou get_posts().

Resetando os loops

Use wp_reset_query() se você usou query_posts() ou mexeu diretamente com a global $wp_query. Use wp_reset_postdata() se você usou the_post() ou setup_postdata(), ou se mexeu com a global $post e precisa restaurar a query ao estado inicial.

Crie uma nova query dentro de uma página ou template

Criar uma nova query dentro de uma página ou template, em alguns casos, é bastante útil. Por exemplo, se você tivesse uma página sobre o Turismo e quisesse exibir os 5 últimos posts sobre este assunto no rodapé.

Para isso, o melhor a fazer é usar a classe WP_Query().

Personalize a Query Principal

Se você quiser alterar o conteúdo que é exibido em uma página, você provavelmente irá precisar modificar a consulta (query) principal. O WordPress tem um hook (gancho) muito útil chamado pre_get_posts. Ele é disparado uma vez que todas as definições da consulta estão prontas, mas antes da consulta real ocorrer. É aqui que vamos modificar as configurações da consulta, se necessário.

Para que isso funcione, você deve colocar a sua função no arquivo functions.php (ou em um plugin). O WordPress precisa, para construir a consulta, saber em qual template deve carregar, por isso, se você colocar a função direto em um arquivo de template como archive.php, por exemplo, será tarde demais.

Todas as funções vão ter uma estrutura semelhante. Primeiro vamos ter certeza de que estamos acessando a query principal. Se não fizermos essa verificação antes, nosso código irá afetar tudo, desde menus a widgets de últimos comentários.

Nós vamos fazer essa verificação usando $query->is_main_query(). Esta função foi adicionada no  WordPress 3.3. Para versões anteriores, utilize a variável global $wp_the_query, como será mostrado mais adiante.

Outras verificações podem ser feitas, por exemplo, se eu quero modificar a query principal, somente na homepage do meu site, eu farei uso de $query->is_home().

Finalmente, as modificações devem ser feitas com o uso do método $query->set( ‘key’, ‘value’ ). Para conhecer todas as modificações possíveis, você pode checar a classe WP_Query no Codex.

Exemplos práticos

Excluindo uma categoria da query principal

Nós vamos verificar se realmente estamos na query principal e se realmente estamos na home do site usando is_home(). Se as respostas às condições forem “true”, então, nós definimos ‘cat’ é igual a ‘-15′, o que diz ao WordPress para excluir esta categoria.

Conforme falamos anteriormente, se você estiver usando a versão 3.2 ou anterior, devemos usar a global $wp_the_query, cujo código ficaria assim:

Alterando a quantidade de posts por página

Vamos supor que você tem um Custom Post Type chamado Evento. Você está exibindo estes eventos em 3 colunas e ao invés da quantidade padrão, que é 10 posts, você quer exibir 18 posts. Se você for alterar a quantidade de posts por página em Configurações > Leitura, no painel administrativo, você irá afetar todo o seu site, não só apenas a listagem de eventos.

Vamos usar o hook pre_get_posts para modificar a quantidade de posts por página somente quando as condições abaixo forem exigidas:

  • Somente na query principal
  • Somente no front-end do site, não no back-end (painel administrativo)
  • Somente no arquivo do Custom Post Type “Evento” (a listagem de posts usando archive-evento.php)

Modificações baseadas em Post Meta

Este exemplo é bem mais complexo. Nós vamos fazer mais algumas modificações em nosso Custom Post Type “Evento”.  Além da quantidade de posts por página que vimos acima, nós queremos mostrar somente os eventos futuros ou ativos (portanto, não aqueles que já terminaram), e classificá-los por data de início com o evento mais próximo primeiro.

Partindo do princípio que já temos um metabox criado, com data de início, data de fim, local, etc, procure armazenar as datas, em postmeta, como timestamps UNIX, assim, ficará mais fácil de trabalhar com estas datas.

Se todas as condições forem cumpridas, aqui estão as modificações que vamos fazer na consulta:

  • Fazer uma meta query para termos certeza de que a data final é maior que a data de hoje
  • Ordenar por meta_value_num (o valor de um custom field)
  • Definir a ‘meta_key’ para data de início, então, o campo meta destes posts serão ordenados por este valor.
  • Colocar em ordem crescente, assim os eventos que começarem antes ficarão antes dos que começarem depois.

São infinitas as possibilidades e fazendo as personalizações usando o hook pre_get_posts, além de ser a forma mais correta e elegante, vai evitar aqueles problemas de páginas 404.

Espero que este artigo ajude muita gente, pois muitos desses códigos aqui já me ajudaram muito! Qualquer dúvida, basta enviar um comentário :-)

Comentários ( 14 )

  • Aline

    Bom dia… Existe a possibilidade de criar um select mostrando as opções de mês e outro de ano, para filtrar os post?

  • Matheus Ilário

    Bom dia Miriam, estou com dúvida para desenvolver a página principal de um site de notícias utilizando pre_get_posts para separar os posts por categoria. Você teria alguma solução ? Desde já agradeço pela atenção.

    • wpmidia

      Olá Matheus!
      Na sua página home, você deve criar cada query separadamente usando a classe WP_Query() de preferencia.
      Uma para cada categoria, nas suas devidas regiões no site…

      Abs.
      Miriam

      • Matheus Ilário

        entendi e apenas utilizar o pre_get_posts para os templates.

        • wpmidia

          o pre_get_posts vai ajudar a alterar a query principal do site, seja na home ou nos templates (page, single, search, etc)

  • José Luis

    Bom dia,
    Quero mudar o modo de exibição dos posts na categoria do wordpress . Não consigo achar nada relacionado ao isso. Peço ajuda se possivel de vocês .
    Gostaria de colocar eles em modo galeria .
    ABs.

Envie seu comentário

Resize-me!