Argumentos WP_Query : Status, Order (Ordem) e Pagination (Paginação)

Portuguese (Português) translation by João Fagner (you can also view the original English article)

Nesta parte da série Dominando WP_Query, você vai aprender sobre alguns dos argumentos que você pode usar com a classe WP_Query, designadamente para:

status
order (ordem)
pagination (paginação)

Você pode usar esses argumentos para buscar postagens regulares do banco de dados, para a consulta de anexos, alterar a forma que os posts são ordenados, especificar quantos posts são exibidos e muito mais

Mas antes de você fazer isso, você precisa entender como argumentos funcionam em WP_Query.

Uma recapitulação de Como Argumentos Funcionam em WP_Query.

Antes de começarmos, vamos dar uma rápida recapitulada como argumentos funcionam em WP_Query. Quando você codificar WP_Query em seus temas ou plugins, você precisa incluir quatro elementos principais:

os argumentos para a consulta, usando os parâmetros que serão abordados neste tutorial
a consulta em si
o loop
terminações: fechando if e while tags e resetando os dados do post

Na prática isto terá uma aparência semelhante a seguinte:

<?php

$args = array(
    // Arguments for your query.
);

// Custom query.
$query = new WP_Query( $args );

// Check that we have query results.
if ( $query->have_posts() ) {

    // Start looping over the query results.
    while ( $query->have_posts() ) {

        $query->the_post();

        // Contents of the queried post results go here.

    }

}

// Restore original post data.
wp_reset_postdata();

?>

Os argumentos são o que diz o WordPress que dados buscar do banco de dados e serão abordados aqui. Estamos focalizando na primeira parte do código:

1	$args = array(
2	// Arguments for your query.
3	);

Como você pode ver, os argumentos estão contidos em um array. Que você vai aprender como codificá-los neste tutorial.

Codificando Seus Argumentos

Há uma maneira específica para codificar os argumentos no array, que é a seguinte:

$args = array(
    'parameter1' => 'value',
    'parameter2' => 'value',
    'parameter3' => 'value'
);

Você deve incluir os parâmetros e seus valores entre aspas simples, usar => entre eles e separe-los com uma vírgula. Se você errar o WordPress não poderá adicionar todos seus argumentos para a consulta ou você pode obter uma tela branco.

Parâmetros de Status

Como você sabe, O WordPress atribui um status para cada post. Se você já converteu um post do Rascunho (Draft) para ser Publicado (Published) ou mesmo enviou para o lixo, isso significa que você alterou o status do post. Você pode usar o parâmetro post_status para consultar posts com um ou mais status.

Os argumentos disponíveis são:

publish: Uma página ou post publicado.
pending: Post está pendente de revisão.
draft: Um post no status de rascunho.
auto-draft: Um post recém criado, sem nenhum conteúdo.
future: Um post para publicar no futuro.
private: Não é visível para os usuários que não estão logados.
inherit: Uma revisão.
trash: Post na lixeira.
any: recupera qualquer status, exceto status de post com 'exclude_from_search' definido como true (ou seja, trash (lixo) e auto-draft (auto-save rascunho)).

Se você não especificar um status em seus argumentos de consulta, WordPress por padrão usa o publish; Se o usuário atual está conectado, incluirá também posts com um status private. Se você executar uma consulta nas páginas admin o WordPress também incluirá os status protegidos, que são o future, draft e pending por padrão.

Então vamos dizer que você está executando um site de eventos e você está usando um tipo de post personalizado do evento, usando a data de publicação como a data em que o evento acontece. Por padrão o WordPress não exibi qualquer evento que ainda não aconteceu: embora você possa agenda-los, sua data prevista é no futuro pois seu status é de post é futuro.

Para contornar esse problema, você simplesmente usar estes argumentos:

1	$args = array(
2	'post_type' => 'event',
3	'post_status' => 'future'
4	);

Isto mostrará apenas os eventos que ainda não aconteceram, como aqueles terão o status de publish. Mas se você também deseja exibir eventos que aconteceram, você pode usar um array de post status para incluir mais de um:

$args = array(
    'post_type' => 'event',
    'post_status' => array(
        'future',
        'publish'
    )
);

O parâmetro post_status é essencial para você consultar por anexos. Isto é porque eles têm um status de inherit, não publish. Para consultar por todos os anexos, você usaria isto:

1	$args = array(
2	'post_type' => 'attachment',
3	'post_status' => 'inherit'
4	);

Uma alternativa, seria substituir inherit (herdar) com any (qualquer) que teria o mesmo efeito.

Parâmetros Order (Ordem)

Há dois parâmetros que você usa para os posts de ordem recuperados por WP_Query: order e orderby. Como seria de esperar, a order define a ordem em que posts serão exibidos no loop e orderby define qual campo no banco de dados que serão ordenados.

Vamos começar olhando para os argumentos de order (ordem).

O Parâmetro order

Existem apenas dois argumentos para ser usado:

ASC: ordem crescente do menor para valores mais altos (1, 2, 3; a, b, c).
DESC: ordem decrescente do mais alto para valores menores (3, 2, 1; c, b, a).

Estes são bastante auto-explicativo. Se você não incluir um argumento order, WordPress padrão usa o DESC.

O Parâmetro orderby

Você pode ordenar seus posts com vários campos:

none: Nenhuma ordem (disponível com a Versão 2.8).
ID: Ordenar pelo id do post. Observe o uso de maiúsculas.
author: Ordenar por autor.
title: Ordenar por título.
name: Ordenar pelo post slug.
type: Ordenar pelo tipo de post.
date: Ordenar por data.
modified: Ordenar pela última data de modificação.
parent: Ordenar pelo id do post/page pai.
rand: Ordem aleatória.
comment_count: Ordenar por número de comentários.
menu_order: Ordenar por Ordem de Página. Usados com mais freqüência para páginas (usando o valor que você adicionar no metabox na tela Editar página) e anexos (usando os campos de número inteiro na inserção / Upload de diálogo Galeria de mídia), mas poderia ser usado para qualquer tipo de post com menu_order habilitado.
meta_value: Ordenar pelo valor para uma meta key (ou campo personalizado). Isso só funciona se você também incluir um parâmetro meta_key em seus argumentos. Meta values (valores de meta) são classificados em ordem alfabética e não numericamente (então 34 virá antes 4, por exemplo).
meta_value_num: Ordem pelo valor numérico da meta. Com o meta_value, você também deve incluir um argumento meta_key em sua consulta.
post__in: Preserva o post ID na ordem dada ao array post__in.

O padrão é date, ou seja, a data que foi publicado um post.

Assim, por exemplo, se você deseja classificar seus posts por título em ordem crescente, você usaria estes argumentos:

1	$args = array(
2	'orderby' => 'title',
3	'order' => 'ASC'
4	);

Ordenação por Multiplos Campos

Não precisa fixar em apenas um campo para ordenar seus posts. Para ordenar por múltiplos campos, você deve usar um array com o parâmetro orderby e (opcionalmente) com o parâmetro order se quiser ordenar cada campo em uma ordem diferente.

Digamos que você tem um campo personalizado de ratings que você deseja usar para ordenar em um site de e-commerce. Você pode ordenar por rating e em seguida título, ambos em ordem crescente, desta forma:

$args = array(
    'orderby' => array(
        'meta_value_num',
        'title'
    ),
    'order' => 'ASC',
    'meta_key' => 'rating'
);

Observe que incluí o argumento meta_key para informar qual campo personalizado que estou usando do WordPress. Você faz isso por causa da maneira que WordPress guarda post metadados: não na tabela wp_posts, mas na tabela wp_postmeta.

Mas se você queria ordenar o rating em ordem decrescente e em seguida o título em ordem crescente? Você simplesmente pode usar outro array:

$args = array(
    'orderby' => array(
        'meta_value_num',
        'title'
    ),
    'order' => array(
        'DESC',
        'ASC'
    ),
    'meta_key' => 'rating'
);

Você pode também ordenar por múltiplos campos quando não estiver usando metadados de post, por exemplo, para ordenar por tipo de post e em seguida data:

$args = array(
    'orderby' => array(
        'type',
        'date'
    ),
    'order' => array(
        'ASC',
        'DESC'
    )
);

Será ordenado por tipo de post em ordem crescente dentro de cada tipo de post, será por data em ordem decrescente.

Parâmetros de Paginação

O próximo conjunto de parâmetros é para paginação. Estes parâmetros te ajuda a definir quantas postagens será consultado e como a paginação funcionará quando exibir os resultados.

Os parâmetros disponíveis são:

nopaging (boolean): Exibi todos os posts ou usa a paginação. O padrão é 'false', ou seja, usar paginação.
posts_per_page (int): Número de posts para mostrar por página.
posts_per_archive_page (int): Número de posts para mostrar por página — apenas em página arquivo.
offset (int): Número de posts para deslocar ou passar por cima.
paged (int): A página no arquivo quais posts serão exibidos.
page (int): Número de páginas apenas para página estática. Mostre os posts que normalmente apareceria apenas na página X de uma Página Estática.
ignore_sticky_posts (boolean): Ignorar post stickiness (fixos)—cujo padrão é false.

Vamos dar uma olhada em alguns exemplos.

Número de Posts e Posts de Offsetting (Compensação)

Por exemplo, para exibir os cinco postes mais recentes:

1	$args = array(
2	'posts_per_page' => '5'
3	);

Ou para exibir cinco posts recentes, excluindo o mais recente:

1	$args = array(
2	'posts_per_page' => '5',
3	'offset' => '1'
4	);

Observe que embora você esteja buscando posts no banco de dados a partir dos seis posts mais recentes, você ainda usa 'posts_per_page' => '5' já que é o número de posts que serão exibidos.

Levando isto um pouco mais longe, você pode escrever duas consultas: um para exibir o post mais recente e um segundo para exibir mais dez posts excluindo o primeiro post recente:

$args = array(
    'posts_per_page' => '1'
);

// Query and loop go here as well as resetting posts.

$args = array(
    'posts_per_page' => '10',
    'offset' => '1'
);

// Second query, loop, and resetting go here.

Você também pode usar posts_per_page para exibir todos os posts:

1	$args = array(
2	'posts_per_page' => '-1'
3	);

Sticky Posts (Posts Fixo)

Normalmente seus posts fixos vão aparecer sempre em primeiro em qualquer consulta: se você deseja sobrescrever isto, deve usar ignore_sticky_posts:

1	$args = array(
2	'posts_per_page' => '5',
3	'ignore_sticky_posts' => true
4	);

Os argumentos acima retornará os cinco posts mais recentes independentemente de serem fixos ou não.

Observe que se você deseja exibir apenas posts fixos, você precisará usar a função get_option() e o argumento post__in como segue:

$sticky = get_option( 'sticky_posts' );

$args = array(
    'posts_per_page' => '5',
    'post__in' => $sticky
);

Acima exibiria os cinco últimos posts fixos: se tiverem menos de cinco anos (por exemplo, três) postagens fixas, não vai exibir posts normais, mas apenas os três posts fixos mais recentes.

Paginação nos Arquivos

Além de definir quantos posts são buscados do banco de dados, você também pode usar os parâmetros de paginação para definir como os posts resultantes irão ser paginados em páginas de arquivo e pesquisa.

Assim, por exemplo em uma página de arquivo, você pode usar este código para exibir 20 posts por página no arquivo:

1	$args = array(
2	'posts_per_archive_page' => '20'
3	);

Observe: o argumento posts_per_archive_page irá substituir posts_per_page.

Você também pode escolher a exibição apenas das páginas que gostaria que aparecesse em uma determinada página como páginas paginadas. Por exemplo, se você quisesse exibir os 20 posts para aparecer na terceira página como no exemplo acima, você usaria isto:

1	$args = array(
2	'posts_per_archive_page' => '20',
3	'paged' => '3'
4	);

Uma maneira alternativa para consultar os mesmos posts seria usar o argumento offset (deslocamento):

1	$args = array(
2	'posts_per_page' => '20',
3	'offset' => '40'
4	);

Isso ignora os primeiros 40 posts (que seria sobre as duas primeiras páginas do arquivo) e agrupa os próximos 20 posts (que seria a terceira página de arquivo. Uma das coisas que eu amo sobre WordPress é que sempre existe mais de uma maneira de conseguir alguma coisa!

Você também pode ativar a opção sem paginação, para garantir que todos os posts sejam exibidos na mesma página:

1	$args = array(
2	'nopaging' => true
3	);

Resumo

A classe WP_Query dá muita flexibilidade quando se trata de determinar quantos posts você quer consultar, qual ordem você deseja exibi-los e qual status do post que você deseja mostrar.

Alguns destes argumentos são essenciais para consultar determinados tipos de post (por exemplo 'post_status' => 'inherited' para anexos), enquanto outros simplesmente dão mais controle sobre a forma como que as consultas são executadas.

Usando esses parâmetros, você pode criar consultas personalizadas que fazem muito mais do que simplesmente exibir os posts publicados recentemente.

Seja o primeiro a saber sobre novas traduções–siga @tutsplus_pt no Twitter!