WP_Query Argumentos: Tags e Categorias

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

Nas partes anteriores desta série, você aprendeu como WP_Query é estruturado e quais são suas propriedades e métodos. A próxima etapa é entender os vários argumentos que você pode usar e a melhor forma de fazê-lo.

WP_Query tem um grande número de argumentos possíveis, que o torna extremamente flexível. Como você pode usá-lo para consultar qualquer coisa realizada em sua tabela wp_posts, WP_Query tem argumentos para cada permutação de consulta, que você pode querer executar em seu conteúdo.

Neste tutorial vou tratar os dois tipos de argumento, para o seguinte:

categorias
tags

Os argumentos para estas duas taxonomias (taxonomies) são semelhantes, mas têm algumas diferenças que você precisa saber para você usá-los efetivamente.

Recapitulando Como os 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: resetando os dados do post (post data)

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 dizem para o WordPress quais dados devem buscar do banco de dados e eles serão abordados aqui. Então todos nós estamos focalizando 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ê aprenderá como codificá-los enquanto você pratica através deste tutorial.

Codificando os 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 separa-los com uma vírgula. Se você errar, o WordPress não adicionará todos seus argumentos para a consulta ou você receberá uma tela em branco.

Parâmetros de Categoria

Vamos começar com parâmetros de categoria. As opções que você tem aqui são as seguintes:

cat (int): usar o id da categoria (category id).
category_name (string): usar o slug da categoria (NÃO o nome).
category__and (array): usar o id da categoria (category id).
category__in (array): usar o id da categoria (category id).
category__not_in (array): usar o id da categoria (category id).

Observe que para nenhum desses você usou o nome de sua categoria. Até mesmo o parâmetro category_name leva o slug como seu valor, não o seu nome. Eu tendo a usar slug, ao invés do ID, as vezes quando eu volto ao meu código em uma data posterior consigo identificar os slugs mais facilmente do que os IDs. No entanto se você acha que os usuários do seu site podem mudar o slug para uma ou mais categorias, eu recomendo usar o ID para evitar quaisquer problemas.

Vamos dar uma olhada em como usar cada uma delas.

O Parâmetro cat

O parâmetro cat é simples: basta usar um ID único da categoria ou uma string de caracteres dos IDs da categoria.

A Consulta por uma categoria parecera com isto:

1	$args = array(
2	'cat' => '12'
3	);

A Consulta por várias categorias parecera com isto:

1	$args = array(
2	'cat' => '12, 13, 14'
3	);

Acima diz ao WordPress para buscar posts que pertessem a qualquer uma das categorias listadas. Se você quiser encontrar posts em cada em um array de categorias, você deve usar o parâmetro category_and, que é mais rapido.

Você também pode usar o parâmetro cat para encontrar posts que estão em uma categoria, mas não estão em outra, usando um sinal de subtração antes do ID da categoria da seguinte maneira:

1	$args = array(
2	'cat' => '12, -13'
3	);

Acima seria uma consulta de posts na categoria 12 mas não na categoria 13.

O parâmetro category_name

O parâmetro category_name usa o slug da categoria, não o nome (confuso, eu sei!). Novamente você pode usá-lo com uma única categoria ou com uma série de categorias para encontrar mensagens que estão em nenhuma das categorias.

Para consultar posts em uma única categoria você deve adicionar:

1	$args = array(
2	'category_name' => 'my-slug'
3	);

E para achar posts em uma ou mais categoria de um número de categorias, você deve usar:

1	$args = array(
2	'category_name' => 'my-slug, your-slug, another-slug'
3	);

Sendo assim, com o parâmetro cat, não encontrará posts que estão em todas as categorias, mas ele vai encontrar posts em qualquer uma destas categorias.

O Parâmetro category__and

Se você quiser encontrar posts que estão em todos em um array de categorias, este é o parâmetro que você usar. Leva os IDs da categoria para assumir seu valor. Então para encontrar posts em todas as três categorias, você usaria:

$args = array(
    'category__and' => array(
        '12',
        '13',
        '14'
    )
);

Observe que utiliza-se um array e não uma string, então você o codifica de uma forma diferente. O parâmetro tem dois sublinhados em seu nome: se usar apenas um não vai funcionar.

O Parâmetro category__in

O próximo parâmetro procura por posts em um ou mais de um array de categorias. Realmente funciona da mesma forma como o parâmetro cat que também leva o ID da categoria com o seu valor.

Para consultar posts em um ou mais de um array de categorias, você deve usar:

$args = array(
    'category__in' => array(
        '12',
        '13',
        '14'
    )
);

Acima buscaria posts de uma ou mais dessas categorias.

O Parâmetro category__not_in

O parâmetro category__not_in faz o que você esperaria: ele consulta os posts que não estão em uma categoria ou em array de categorias.

Excluir posts de uma categoria, você deve usar o seguinte:

1	$args = array(
2	'category__not_in' => '12'
3	);

Excluindo posts de um conjunto de categorias:

$args = array(
    'category__not_in' => array(
        '12',
        '13',
        '14'
    )
);

Exclui os posts de qualquer uma dessas categorias.

Parâmetros de Tag

Tags têm parâmetros ligeiramente diferentes de categorias: você não pode trabalhar-las baseado em seu conhecimento dos parâmetros de categoria, fiquei preocupado agora!

Os parâmetros de tag são:

tag (string): usar tag slug.
tag_id (int): usar tag id.
tag__and (array): usar tag ids.
tag__in (array): usar tag ids.
tag__not_in (array): usar tag ids.
tag_slug__and (array): usar tag slugs.
tag_slug__in (array): usar tag slugs.

Vamos olhar cada uma delas.

A Parâmetro tag

O parâmetro tag leva o slug da tag a assumir o seu valor e pode ser usado para procurar posts com uma tag ou com qualquer string de tags.

Então para encontrar posts com um tag você deve usar:

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

E para encontrar posts com tags de um array de tags:

1	$args = array(
2	'tag' => 'my-tag, your-tag, another-tag'
3	);

Observe que as consultas acima é por posts com qualquer uma das tags do array, mas não todas elas.

O Parâmetro tag_id

O parâmetro tag_id funciona de forma semelhante ao parâmetro de cat: leva o ID da tag e pode ser usado com uma tag única ou como várias tags.

Para localizar posts com uma única tag você deve usar:

1	$args = array(
2	'tag_id' => '21'
3	);

Para encontrar posts com uma ou mais tags de uma string de IDs de tag:

1	$args = array(
2	'tag_id' => '21, 22, 23'
3	);

Você também pode usar tag_id para excluir tags, mesmo quando estiver usando para tags única ou para várias tags.

Consulta por posts exceto aqueles com uma tag determinada, para isso você deve usar:

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

Para achar posts com uma das duas tags, mas sem a outra tag, você deve usar isto:

1	$args = array(
2	'tag_id' => '21, -22, 23'
3	);

A consulta de posts acima buscará um ou ambos as tags 21 ou 23 mas não a tag 22.

O Parâmetro tag__in

Este parâmetro te permite encontrar posts com um ou mais tags em um array. Ele funciona da mesma maneira que a tag quando é usado com uma array:

1	$args = array(
2	'tag_in' => array(
3	'21',
4	'22',
5	'23'
6	)
7	);

Isto irá consultar posts com qualquer tags ou todas listadas. Se você quiser encontrar posts com todas as tags, você deve usar a tag__and, que será abordado em um momento.

O Parâmetro tag__not_in

O parâmetro tag__not_in te permite consultar posts que não têm uma determinada tag ou array de tags.

Para excluir uma tag deve usar algo como isto:

1	$args = array(
2	'tag__not_in' => array( '21' )
3	);

Note que você ainda precisa usar uma array, mesmo que você esteja usando apenas uma tag. Para mais tags, use:

$args = array(
    'tag__not_in' => array(
        '21',
        '22',
        '23'
    )
);

Isto irá consultar posts que não têm qualquer uma das tags acima.

Os Parâmetros tag_slug__and e tag_slug__in

Estes dois parâmetros se comportam exatamente da mesma forma que os parâmetros tag__and e tag__in, exceto que você precisar usar o slug da tag em seu array em vez da identificação de tag.

Por exemplo para encontrar posts que têm ambos um par de tags, você usar o tag__slug_in:

$args = array(
    'tag_slug__in' => array(
        'my-tag',
        'your-tag',
        'another-tag'
    )
);

Para encontrar posts com qualquer uma dessas tags. Você também poderia usar o parâmetro de tag com uma string de slug de tag para ter o mesmo resultado.

Para incluir posts com todo um conjunto de tags, use tag_slug__and:

$args = array(
    'tag_slug__and' => array(
        'my-tag',
        'your-tag',
        'another-tag'
    )
);

Em vez de consultar posts com qualquer uma das tags, apenas consulte posts que tem todas as tags.

Resumo

Consultar seus posts por categoria e/ou tag é algo que tem uma boa chance de acontecer e será a ocasião perfeita para usar WP_Query. Usando os argumentos acima, e combinando-os, se necessário, você pode criar poderosos argumentos para extrair exatamente os dados que você precisa do banco de dados.

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