Postagens, páginas e tipos de postagem

Nesta parte desta série sobre WP_Queryvocê aprenderá a usar WP_Query para consultar postagens, páginas e tipos de postagem personalizados. Você pode consultar postagens e páginas específicas ou executar uma consulta para retornar postagens de um ou mais tipos de postagem.

Uma recapitulação de como os argumentos funcionam no WP_Query

Antes de começarmos, vamos recapitular rapidamente como os 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 parâmetros que serão abordados neste tutorial
• a própria consulta
• o laço
• finalizando: fechando as tags if e while e redefinindo os dados da postagem

Na prática, isso será algo como o seguinte:

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 devem ser buscados no banco de dados e são esses que abordarei aqui. Então, tudo o que estamos focando aqui é a primeira parte do código:

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

Como você pode ver, os argumentos estão contidos em uma matriz. Você aprenderá a codificá-los enquanto trabalha neste tutorial.

Codificando seus argumentos

Existe uma maneira específica de codificar os argumentos na matriz, que é a seguinte:

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

Você deve colocar os parâmetros e seus valores entre aspas simples, use => entre eles e separe-os com uma vírgula. Se você errar, o WordPress pode não adicionar todos os seus argumentos à consulta ou você pode obter uma tela branca.

Consulta de postagens ou páginas únicas

Vamos começar com o cenário mais simples: executar uma consulta para encontrar uma postagem ou página específica.

Consultando uma postagem

Para encontrar uma postagem específica (ou conjunto de postagens), você tem duas opções:

• p (int): Use o ID da postagem.
• name (fragmento): Use post slug.

Você pode usar esses parâmetros com qualquer tipo de postagem, incluindo postagens, páginas, anexos e tipos de postagem personalizados. Por padrão, o WordPress consultará o 'post' tipo de postagem e não retornar páginas ou tipos de postagem personalizados — se você quiser fazer isso, precisará adicionar mais argumentos ou usar um argumento diferente, que abordarei mais adiante neste tutorial.

Então, para retornar um post específico, você usaria um destes:

$args = array(
    'p' => 224
);

ou:

$args = array(
    'name' => 'how-to-create-a-website'
);

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

Usando o name O parâmetro facilita a identificação do que sua consulta buscará no banco de dados quando você revisitar seu código posteriormente, mas existe o risco de que não funcione se um dos usuários do seu site alterar o slug de postagem. O ID da postagem não pode ser alterado, por isso é mais seguro.

Aqui está o resultado da execução das duas consultas acima para mim.

Consulta para uma página

Para consultar uma página específica, você tem duas opções novamente:

• page_id (int): Use o ID da página.
• pagename (fragmento): Use slug de página.

Portanto, para executar uma consulta buscando apenas uma página específica do banco de dados, você usaria um destes:

$args = array(
    'page_id' => '20'
);

ou:

$args = array(
    'pagename' => 'domain-name-generator'
);

Você deve ter notado que passamos 20 como uma corda para page_id em nosso exemplo. Esse 20 é convertido em um inteiro porque page_id espera que o parâmetro seja um inteiro.

Recuperei as seguintes páginas executando as consultas acima.

Consultando uma postagem de outro tipo

Para executar uma consulta para uma postagem de outro tipo de postagem, incluindo um tipo de postagem personalizado, você também usaria o post_type parâmetro. Abordarei isso com um pouco mais de detalhes posteriormente neste tutorial, mas em resumo, para consultar um único post no product tipo de postagem personalizado, você usaria isso:

$args = array(
    'p' => '46',
    'post_type' => 'product'
);

Ou para consultar um anexo, você usaria:

$args = array(
    'p' => '248',
    'post_type' => 'attachment'
);

Recebo uma imagem se eu executar a segunda consulta.

Como consultar páginas filhas

Às vezes, você pode precisar recuperar todas as páginas filhas de uma determinada página, por exemplo, se seu site tiver uma estrutura de página hierárquica e você quiser exibir uma lista em cada página filha dessa página.

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

• post_parent (int): Use o ID da página para retornar apenas as páginas filhas. Defina como 0 para retornar apenas as entradas de nível superior.
• post_parent__in (variedade): Use uma matriz de IDs de postagem.
• post_parent__not_in (variedade): Use uma matriz de IDs de postagem.

Vamos dar uma olhada em cada um deles.

O primeiro, post_parentpermite consultar páginas que 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, você usaria isto:

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

Observe que você deve incluir o post_type argumento como o tipo de postagem padrão que WP_Query procura é post.

Levando isso adiante, é assim que você o usaria para encontrar 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 este parâmetro para identificar páginas de nível superior, ou seja, aquelas sem pai:

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

Mas e se você quiser identificar filhos de várias páginas? Você também pode fazer isso com o post_parent__in parâmetro. Isso leva uma matriz de IDs de postagem.

Então, para consultar os filhos de duas de suas páginas, você usaria isto:

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

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

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

Consultando várias postagens

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

• post__in (variedade): Use IDs de postagem.
• post__not_in (variedade): Use IDs de postagem.

o post__in argumento pode ser usado para todos os tipos de postagem e recebe uma matriz de IDs. Então, para gerar uma lista de postagens específicas, você usaria isto:

$args = array(
    'post__in' => array(
        '704',
        '224',
        '218',
        '152'
    )
);

Você deve ter notado que a lista de postagens recuperadas não inclui postagens com IDs 704 e 224. Isso ocorre porque o WordPress só buscará postagens publicadas por padrão. É possível recuperar postagens com status diferentes definindo o valor de post_status argumento para 'any'. Você pode aprender mais sobre esse argumento e seus possíveis valores válidos aqui.

$args = array(
    'post__in' => array(
        '704',
        '224',
        '218',
        '152'
    ),
    'post_status' => 'any'
);

Você provavelmente também está se perguntando sobre a primeira postagem na lista recuperada. Observe que, se você usar o post__in argumento para buscar posts, o WordPress ainda buscará posts fixos, mesmo que não estejam na sua lista, como você pode ver na imagem acima. Para omiti-los, você usa o ignore_sticky_posts argumento:

$args = array(
    'post__in' => array(
        '704',
        '224',
        '218',
        '152'
    ),
    'post_status' => 'any',
    'ignore_sticky_posts' => 'true'
);

o post__not_in O argumento funciona de maneira semelhante, novamente pegando uma matriz de IDs de postagem, mas produzirá todo o resto, exceto as postagens listadas. Você normalmente o combinaria com outros argumentos para evitar a saída de uma lista enorme de postagens.

Tenha em mente que você não pode usar ambos post__in e post_not__in argumentos na mesma consulta.

Então, para consultar todos os posts do product tipo de postagem, mas exclua alguns:

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

Então, para combinar isso com um de nossos exemplos anteriores, veja como você consultaria todas as páginas de nível superior, exceto a atual:

$current_page_ids = array( get_the_ID() );

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

Consultando tipos de postagem

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

• post: Uma postagem.
• 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 revisões e tipos com 'exclude_from_search' definido como true quando foram registrados
• Tipos de postagem personalizados (por exemplo, product).

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

O valor para post_type é normalmente definido para post por padrão. No entanto, torna-se any sempre que usar o tax_query argumento em suas consultas.

Então, para dar um exemplo simples, veja como você consultaria todas as páginas do seu site:

$args = array(
    'post_type' => 'page'
);

Tipos de postagem personalizados

Consultar um tipo de postagem personalizado é simples: use o nome que você deu ao tipo de postagem ao registrá-lo, não o título que é usado nos menus de administração. Então, digamos que você registrou seus tipos de postagem de produto usando register_post_type() do seguinte modo:

function register_product() {

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

    register_post_type( 'product', $args );
}

O valor que você usa para o post_type argumento ao consultar produtos não é 'Product' ou 'Products' mas 'product':

$args = array(
    'post_type' => 'product'
);

Anexos

Por padrão, se você tentar executar uma consulta de anexos, não funcionará, pois o WordPress define o post_status de anexos para inherit e WP_Query padrão para 'post_status' => 'publish' a menos que você especifique o contrário. Então, se você quiser consultar anexos, você devo incluir o post_status argumento:

$args = array(
    'post_type' => 'attachment',
    'post_status' => 'inherit'
);

Observe que você também pode usar any ao invés de inherit.

Resumo

Usando WP_Query criar consultas personalizadas para postagens e tipos de postagem é algo que faço muito. Como você viu nos exemplos aqui, há muitas possibilidades:

• Use-o para consultar páginas de nível superior em seu site.
• Use-o para consultar postagens de um tipo de postagem específico.
• Use-o para consultar todas as postagens, exceto as que você especificar.
• Use-o para consultar todos os filhos da página atual.

Existem muitas outras possibilidades usando os argumentos abordados aqui, mas isso deve lhe dar uma amostra.

Este post foi atualizado com contribuições de Nitish Kumar. Nitish é um desenvolvedor web com experiência na criação de sites de comércio eletrônico em várias plataformas. Ele passa seu tempo livre trabalhando em projetos pessoais que facilitam sua vida cotidiana ou fazendo longas caminhadas noturnas com os amigos.