Argumentos WP_Query: Posts, Páginas e Tipos de Posts (Post Types)

() translation by (you can also view the original English article)

Nesta parte da série sobre WP_Query, você aprenderá como usar WP_Query para consultar posts, páginas e tipos de posts personalizado. Você pode fazer consultas especificas para posts e páginas, ou você pode executar uma consulta para retornar posts de um ou mais tipos de post.

Recapitulando Como Argumentos Funcionam em WP_Query

Antes de começarmos, vamos dar uma rápida recapitulada em como argumentos funcionam em WP_Query. Quando você codifica 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 as tags if e while 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 ao WordPress quais dados serão retornados do banco de dados e eles serão abordados aqui. Então todos nós estamos focalizando aqui é a 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. Você vai aprender como codificá-los através deste tutorial.

Codificando os Seus Argumentos

Existe 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, use => entre eles e separe-os com uma vírgula. Se você passar valores errados o WordPress pode não adicionar todos os seus argumentos para a consulta ou você pode obter uma tela branca.

Consulta Única de Posts ou Páginas

Vamos começar com o cenário mais simples: executar uma consulta para localizar uma página ou post específico.

Consultar um Post

Para encontrar um post específico (ou conjunto de posts), você tem duas opções:

p (int): Usar ID post (post ID).
name (string): Usar o slug do post (post slug).

Você pode usar estes parâmetros com qualquer tipo de post incluindo posts, páginas, anexos e tipos de post personalizados. Por padrão o WordPress irá consultar pelo 'post', do tipo de post e não retornará páginas ou tipos de post personalizado—se você quiser fazer isso, você precisará adicionar mais argumentos ou usar um argumento diferente, que eu explicarei mais a frente neste tutorial.

Então, para retornar um post específico você deverá usar um desses argumentos:

1	$args = array(
2	'p' => '32'
3	);

ou:

1	$args = array(
2	'name' => 'post_slug'
3	);

Observe que o parâmetro de name (nome) leva o post slug como seu argumento, não o seu título.

Usar o parâmetro name (nome) facilita a identificação do que sua consulta irá buscar no banco de dados quando você revisitar seu código em uma data posterior, mas há o risco de que não vai funcionar se um dos usuários do seu site for alterar o post slug. O ID do post não pode ser alterado, por isso é mais seguro.

Consulta de Uma Página

A consulta para uma página específica, novamente você tem duas opções:

page_id (int): Usar o ID da página (page ID).
pagename (string): Usar o slug da página (page slug).

Então, para executar uma consulta que busca apenas uma página específica do banco de dados, você usaria um desses:

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

ou:

1	$args = array(
2	'pagename' => 'page_slug'
3	);

Consulta de um Post de Outro Tipo

Para executar uma consulta para um tipo de post de outro tipo, incluindo um tipo de post personalizado, você tem que usar o parâmetro post_type. Falarei mais detalhadamente no final deste tutorial, a consulta para um post único em product um tipo de post personalizado, você deverá usar isto:

1	$args = array(
2	'p' => '46',
3	'post_type' => 'product'
4	);

Ou a consulta para um anexo, você usaria:

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

Consulta por Páginas Filhas

Às vezes precisamos recuperar todas as páginas que são filhas de uma determinada página, por exemplo, se seu site tem uma estrutura hierárquica de página e você deseja exibir uma lista em cada página das página filhas.

Nota: Você não faria isso com posts como eles não são hierárquicos, embora com um o tipo de post personalizado seja hierárquico.

Você tem três argumentos que você pode usar para fazer isso:

post_parent (int): Usa o ID da página (page ID) para retornar somente as páginas filhas. Definido como 0 para retornar apenas as entradas de alto nível.
post_parent__in (array): Usar um array de IDs de post (post IDs).
post_parent__not_in (array): Usar um array de IDs de post (post IDs).

Vamos dar uma olhada em cada um deles.

O primeiro, post_parent, permite que você consulte quais páginas são filhas de uma página específica.

Então para encontrar todas as páginas que são filhas de uma determinada página, utilize este:

1	$args = array(
2	'post_type' => 'page',
3	'post_parent' => '2'
4	);

Note que você tem que incluir o argumento de post_type com o tipo de post padrão para WP_Query procura é post.

Levando mais longe, isto é como você o usaria para encontrar os filhos da página atual:

$current_page_id = get_the_ID();

$args = array(
    'post_type' => 'page',
    'post_parent' => $current_page_id
);

Você também pode usar esse parâmetro para identificar páginas do nível superior, ou seja, aquelas sem um pai:

1	$args = array(
2	'post_type' => 'page',
3	'post_parent' => '0'
4	);

Mas e se você deseja identificar filhos de várias páginas? Você pode fazer isso também, com o parâmetro post_parent__in. Isto leva a uma array de IDs de post (post IDs).

Então a consulta para os filhos de duas de suas páginas, utilize isto:

$args = array(
    'post_type' => 'page',
    'post_parent__in' => array(
        '2',
        '4'
    )
);

Você também pode excluir páginas filhas da sua consulta, usando o parâmetro de post_parent__not_in:

$args = array(
    'post_type' => 'page',
    'post_parent__not_in' => array(
        '2',
        '4'
    )
);

Consultando Múltiplos Posts

Também é comum executar uma consulta para incluir ou excluir vários posts. Você tem dois argumentos que você pode usar para isso:

post__in (array): Usar os IDs do post (post IDs).
post__not_in (array): Usar os IDs do post (post IDs).

O argumento post__in pode ser usado para todos os tipos de post recebe um array de IDs. Então para a saída de uma lista de posts específicos, use este:

1	$args = array(
2	'post__in' => array(
3	'36',
4	'52',
5	'246',
6	'354'
7	)
8	);

Nota: Se você usar este argumento para buscar posts, WordPress ainda trará posts fixos (sticky posts), mesmo se eles não estiverem na sua lista. Para omiti-los, você pode usar o argumento ignore_sticky_posts:

$args = array(
    'post__in' => array(
        '36',
        '52',
        '246',
        '354'
    ),
    'ignore_sticky_posts' => 'true'
);

O argumento post__not_in funciona de forma semelhante, tendo novamente um array de post IDs, mas será tudo exceto os posts de saída listados. Você normalmente poderia combiná-lo com outros argumentos para evitar a saída de uma lista enorme de posts.

Então a consulta para todos os posts do tipo de post produto (product), mas excluindo alguns:

$args = array(
    'post_type' => 'product',
    'post__not_in' => array(
        '36',
        '52',
        '246',
        '354'
    )
);

Então combinando isto com um dos nossos exemplos anteriores, esse exemplo mostra como você faria a consulta para todos os níveis superior das páginas, exceto a atual:

$current_page_ids = array( get_the_ID() );

$args = array(
    'post_parent' => '0',
    'post__not_in' => $current_page_ids
);

Note que se você também já registrou um tipo de post hierárquico, você precisará incluir o parâmetro post_type neste código para apenas consultar páginas.

Consultar Tipos de Post

Em alguns dos exemplos acima, eu usei o parâmetro post_type para identificar mensagens de um determinado tipo. Vamos dar uma olhada os argumentos que você pode usar com o parâmetro:

post: Um post.
page: Uma página.
revision: Uma revisão.
attachment: Um anexo.
nav_menu_item: Um item do menu de navegação.
any: recupera qualquer tipo, exceto as revisões e tipos com 'exclude_from_search' definida como true quando estavam registradas.
Tipos de Post Personalizados (por exemplo, product).

Como vimos acima você pode usar esse parâmetro com outros argumentos para tornar sua consulta mais específica.

Então para dar um exemplo simples, aqui está como você poderia consultar por todas as páginas do seu site:

1	$args = array(
2	'post_type' => 'page'
3	);

Tipos de Posts Personalizado

Consulta para um tipo de post personalizado é simples: use o nome deste tipo de post quando registrá-lo, não o título que é usado nos menus do admin. Então, digamos que você registrou seu tipo de post produto (product) usando register_post_type() como abaixo:

function register_product() {

    $args = array(
        'name' => __( 'Products', 'tutsplus' ),
        'singular_name' => __( 'Product', 'tutsplus' )
    );

    register_post_type( 'product', $args );
}

O valor utilizado para o argumento de post_type ao consultar para produtos não é 'Product' ou 'Products', mas 'product':

1	$args = array(
2	'post_type' => 'product'
3	);

Anexos (Attachments)

Por padrão se você tentar executar uma consulta por anexos não vai funcionar, como WordPress define o post_status de anexos para inherit (herdar) e WP_Query padrão é 'post_status' => 'publish' a menos que você especifique o contrário. Então se você deseja consultar por anexos você deve incluir o argumento post_status:

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

Note que você também poderia usar any (qualquer) em vez de inherit (herdar).

Resumo

Usando WP_Query para criar consultas personalizadas para posts e tipos de post é algo que faço constantemente. Como você viu nos exemplos, há uma variedade de possibilidades:

Usá-lo para consultar as páginas de nível superior em seu site.
Usá-lo para consultar posts de um tipo específico de post.
Usá-lo para consultar todos os posts, exceto os que você especificar.
Usá-lo para consulta todas as páginas filhas da página atual.

Há muito mais possibilidades, usando os argumentos cobertos aqui, mas isso deve servir de amostra.

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