Argumentos WP_Query: Taxonomias

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

Até agora nesta série, você aprendeu como WP_Query é estruturado e quais são suas propriedades e métodos. Agora nós estamos olhando para os vários argumentos que você pode usar com WP_Query e como codifica-los.

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, tem argumentos para cada permutação de consulta, que você pode querer executar em seu conteúdo.

Neste tutorial eu vou abordar os argumentos para poder consultar termos de taxonomia (taxonomy).

Recapitulando Como Argumentos Funcionam em WP_Query

Antes de começarmos, vamos dar uma rápida recapitulação de 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 o 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 ao WordPress quais dados buscar do banco de dados que serão abordados aqui. Então o que 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 no array. Você vai aprender como codificá-los através deste 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-os 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.

Os Parâmetros de Taxonomia

Definir parâmetros para termos de taxonomia é um pouco mais complicado do que para categorias e tags uma vez que você use o tax_query. Dentro deste argumento, você escreverá um array aninhada de argumentos para especificar a taxonomia e o termo usando estes parâmetros:

taxonomy (string): Taxonomia (Taxonomy).
field (string): seleciona o termo da taxonomia (taxonomy) por ('term_id (default), 'name' ou 'slug').
terms (int/string/array): termo de taxonomia (Taxonomy term(s).
include_children (boolean): Se deve ou não incluir filhos de taxonomias hierárquicas. O padrão é true.
operator (string): Operador para testar. Os valores possíveis são 'IN' (padrão), 'NOT IN', 'AND'.

O fato de você ter o parâmetro do operador (operator) significa que você não precisa escolher entre vários argumentos disponíveis para definir se você está incluindo ou excluindo termos (como você faz para tags e categorias), mas use tax_query para todas as taxonomia-relacionada (taxonomy-related).

Se você deseja consultar múltiplas taxonomias, você também pode usar o parâmetro de relação (relation) antes de seu array (uma para cada taxonomia) tudo com AND ou OR para especificar se você deseja encontrar posts com todos os termos, ou qualquer um deles.

Isto é mais facilmente explicado com alguns exemplos.

Consulta por Um Termo de Taxonomia

Este é o cenário mais simples e envolve apenas o uso de um array aninhado:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'field' => 'slug',
            'terms' => 'my-term-slug',
        )
    )
);

As consultas acima para posts com o termo my-term-slug na taxonomia my-taxonomy. Note que você também precisa usar o parâmetro field para identificar qual campo você está usando para identificar o termo, a menos que você esteja usando o termo ID que é o padrão. Se você quisesse usar o ID do termo (term) você usaria algo assim:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'terms' => '11'
        )
    )
);

Usar o ID torna mais difícil para você identificar a sua consulta, caso a procure em uma data posterior, mas evita qualquer problema em potencial caso os usuários editem o termo do slug.

Consulta Por Múltiplos Termos em Uma Taxonomia

Se você deseja identificar posts com um ou mais de um em um array de termos na mesma taxonomia, você deverá escreve um array aninhado, mas adicionando um array de termos.

Por exemplo a consulta de posts com qualquer um de uma lista de IDs de termo de sua taxonomia, você deve usar:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'terms' => array(
                '11',
                '12'
            )
        )
    )
);

Mas e se você quisesse consultar posts com todos estes termos? Você precisará usar o parâmetro operator (operador) dentro do seu array aninhado:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'terms' => array(
                '11',
                '12'
            ),
            'operator' => 'AND'
        )
    )
);

Observe que o primeiro exemplo usa, na verdade, o operador IN para encontrar posts com qualquer um dos termos, mas como este é o padrão não precisa especificá-lo em seus argumentos.

Outro cenário é se você deseja consultar posts que não têm qualquer array de termos em uma taxonomia da qual você goste:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'terms' => array(
                '11',
                '12'
            ),
            'operator' => 'NOT IN'
        )
    )
);

Aqui eu já substituiu o operador AND com NOT IN, que significa que WordPress irá encontrar posts sem qualquer um dos termos do array.

Observe que, se você preferir usar slugs em vez IDs de termo, você pode fazer isso com qualquer um desses cenários. O último exemplo ficaria assim:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'field' => 'slug',
            'terms' => array(
                'my-slug',
                'your-slug'
            ),
            'operator' => 'NOT IN'
        )
    )
);

Outro cenário é se você deseja consultar por posts que tem um termo, mas não tem outro. Ele usa o operador IN (que você não precisa incluir, porque é o padrão), com um sinal de subtração antes do ID de quaisquer termos que você deseja excluir:

$args = array(
    'tax_query' => array(
        array(
            'taxonomy' => 'my-taxonomy',
            'terms' => array(
                '11',
                '-12'
            )
        )
    )
);

Consultando posts com termo (term) 11 mas não o termo (term) 12.

Consulta por Termos de Múltiplas Taxonomias

Se você quer trabalhar com mais de uma taxonomia, você precisará criar mais de um array. Vejamos o exemplo mais simples, a consulta de posts com um termo de taxonomy1 e um termo de taxonomy2:

$args = array(
    'tax_query' => array(
        'relation' => 'AND',
        array(
            'taxonomy' => 'taxonomy1',
            'field' => 'slug',
            'terms' => array( 'slug-one' )
        ),
        array(
            'taxonomy' => 'taxonomy2',
            'field' => 'slug',
            'terms' => array( 'slug-two' )
        )
    )
);

Aqui escrevi dois arrays aninhadas: um para cada taxonomia, usando os mesmos argumentos, assim como eu fiz para os exemplos usando apenas uma taxonomia. Já precedido com o argumento da relation (relação). Você precisa incluir o argumento relation para dizer o WordPress se está procurando por todos os posts ou por alguns em cada array de saída. Funciona da seguinte maneira:

Se você usar a 'relation' => 'AND', WordPress irá buscar os posts especificados no primeiro array e no segundo array. Como no exemplo acima, serão consultados apenas posts com ambos slug-one em taxonomy1 slug e o slug-two em taxonomy2.
Se você usar a 'relation' => 'OR', WordPress irá buscar posts de saída do primeiro array ou do segundo array. Então neste caso você retornará posts tanto com slug-one ou com slug-two slug (ou ambos).

Este é o código que você deve usar se você estiver procurando por posts com qualquer uma dos dois slugs:

$args = array(
    'tax_query' => array(
        'relation' => 'OR',
        array(
            'taxonomy' => 'taxonomy1',
            'field' => 'slug',
            'terms' => array( 'slug-one' )
        ),
        array(
            'taxonomy' => 'taxonomy2',
            'field' => 'slug',
            'terms' => array( 'slug-two' )
        )
    )
);

Você também pode olhar para mais de um termo em uma taxonomia determinada adicionando-o ao array:

$args = array(
    'tax_query' => array(
        'relation' => 'OR',
        array(
            'taxonomy' => 'taxonomy1',
            'field' => 'slug',
            'terms' => array( 'slug-one' )
        ),
        array(
            'taxonomy' => 'taxonomy2',
            'field' => 'slug',
            'terms' => array(
                'slug-two',
                'slug-three'
            )
        )
    )
);

Combinando o argumento da relação (relation) com consultas aninhadas também usando o argumento de operador (operator), você pode criar consultas muito complexas. Os argumentos abaixo poderá consultar posts com um termo de uma taxonomia, mas sem um termo de taxonomia de outro:

$args = array(
    'tax_query' => array(
        'relation' => 'AND',
        array(
            'taxonomy' => 'taxonomy1',
            'field' => 'slug',
            'terms' => array( 'slug-one' ),
            'operator' => 'NOT IN'
        ),
        array(
            'taxonomy' => 'taxonomy2',
            'field' => 'slug',
            'terms' => array( 'slug-two' )
        )
    )
);

Observe que utilizei 'relation' => 'AND' aqui: se usar OR, seria consultado posts com slug-two e posts sem slug-one, ao invés de posts que têm slug-two, mas não é slug-one, que é o que eu estou procurando.

Poderia concebivelmente levar isso além buscando seus termos de taxonomias no entanto se você estiver procurando: usando o argumento operator em ambas as buscas aninhadas ou incluindo uma busca aninhada adicional para buscar os termos de outra taxonomia.

Uma Nota Sobre o Argumento tax

Você pode estar se perguntando por que eu não inclui o argumento {tax}, onde você simplesmente escreveria o seu argumento da seguinte maneira:

1	$args = array(
2	'taxonomy1' => 'slug-one'
3	);

Você pode estar familiarizado com esta forma de consultar as taxonomias, caso tenha utilizado no passado, mas agora está obsoleto e você não deve usá-lo. Então mude para 'tax_query'!. Usando tax_query você terá muito mais flexibilidade, enfim.

Resumo

É um pouco mais complicado do que categorias e tags, a consulta por taxonomias, você precisa se familiarizar com o argumento de tax_query.

No entanto, como já vimos, este é um argumento muito poderoso que lhe dá um escopo e flexibilidade para consultar seu banco de dados de qualquer maneira que você desejar.

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