Dominando WP_Query: 10 Exemplos Úteis

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

Agora que aprendemos quase tudo sobre a classe WP_Query é hora de experimentar alguns exemplos. Nesta parte iremos trabalhar em 10 cenários diferentes para utilizar a classe WP_Query e suas funções relacionadas.

Será um divertido exercício e eu espero que seja igualmente educacional. Vamos começar!

Vamos Relembrar Rapidamente Como Criar o Loop com WP_Query

Apenas para tornar este artigo mais compreensível diferenciando um pouco da série "Dominando WP_Query" eu deveria fazer um nano-tutorial sobre como criar loops de WordPress com a classe WP_Query.

Não é muito diferente do que criar um loop padrão. Um loop típico do WordPress é assim:

<?php

if ( have_posts() ) {

    while ( have_posts() ) {

        the_post();

        // Post data goes here.

    }

}

?>

E criando um loop com a classe WP_Query tem apenas algumas diferenças:

<?php

$args = array(
    'category_name' => 'news',
    'posts_per_page' => 3
);

$my_query = new WP_Query( $args );

if ( $my_query->have_posts() ) {

    while ( $my_query->have_posts() ) {

        $my_query->the_post();

        // Post data goes here.

    }

}

// Reset the `$post` data to the current post in main query.
wp_reset_postdata();

?>

Vamos ver a diferença entre os dois:

Definimos alguns argumentos para nossa instância WP_Query,
Nós instanciamos a classe WP_Query,
Nós adicionamos $my_query-> para o início das funções have_posts() e the_post() (agora eles são métodos da classe WP_Query),
E nós resetamos os dados do $post para que possam retornar a consulta principal.

Agora sabemos como criar um loop com WP_Query e a diferença entre um loop regular e um loop criado com WP_Query. Não vamos criar loops em cada exemplo (por uma questão de manter o tutorial curto e focado no tópico), então você pode se referir a esta seção sempre que você precisa criar um loop com os exemplos abaixo.

Exemplo #1: Posts de um Autor Deste Ano

Digamos que você deseja listar posts de um determinado autor escrito no ano atual em especial da seção "Posts de um Autor Deste Ano". Uma simples combinação de dois parâmetros WP_Query será suficiente:

<?php

// Get the year we're in.
$current_year = date( 'Y' );

// Setup arguments.
$args = array(
    // Get the author with the nicename "john".
    'author' => 'john',
    // Get his posts from this year.
    'year'   => $current_year
);

// Instantiate new query instance.
$my_query = new WP_Query( $args );

?>

Use essa consulta no loop e pronto!

Exemplo #2: "Últimas Postagens Desta Categoria" (Exceto o Post Atual)

Digamos que você deseja criar um loop e abaixo de cada post em suas páginas de um post único (single post pages) listar os posts mais recentes da categoria que o post está contido. Claro, você tem que excluir o post atual no caso de ser um dos mais recentes posts da categoria. Aqui está como você pode criar a sua consulta com parâmetros 'cat' e 'post__not_in':

<?php

// Get the current post id.
$current_post_id = get_the_ID();

// Get the current post's category (first one if there's more than one).
$current_post_cats = get_the_category();
$current_post_first_cat_id = $current_post_cats[ 0 ]->term_id;

// Setup arguments.
$args = array(
    // Get category's posts.
    'cat' => $current_post_first_cat_id,
    // Exclude current post.
    'post__not_in' => array( $current_post_id )
);

// Instantiate new query instance.
$my_query = new WP_Query( $args );

?>

Para o loop, sugiro criar três ou quatro colunas com miniaturas de post acima dos títulos do post. Vai ficar bem legal, debaixo do post e antes da seção de comentários.

Exemplo #3: "Posts Mais Populares" Ordenado pela Contagem de Comentários

WordPress não foi construído com um sistema de "contagem de visualização de post" e os plugins que fornecem essa funcionalidade são famosos por englobar todo o site (porque em cada modo de exibição do post esses plugins escrevem no banco de dados repetidamente para gravarem a contagem de visualização). No entanto, há um outro tipo de medição para determinar quais posts são mais "populares": contagem de comentários. E ao contrário da contagem de visualizações as contagens de comentário já estão no banco de dados — a classe WP_Query torna super fácil ordenar os posts pela contagem de comentários:

<?php

// Setup arguments.
$args = array(
    // Order by comment count.
    'orderby' => 'comment_count'
);

// Instantiate new query instance.
$my_query = new WP_Query( $args );

?>

Veja como isto é fácil? Agora imagine a criação de um modelo de página personalizada com um loop para executar a consulta — com uma página "Os Posts Mais Comentados".

Exemplo #4: Configuração de um Slider Simples

Ao usar o WordPress para criar sites corporativos, portfólios ou revistas web, sliders tornaram-se algo "obrigatório" por padrão industrial. Eu não sou realmente um fã de sliders (acho que é má UX), mas a web parece que gostou, então não posso simplesmente dizer não aos meus clientes enquanto faço os sites para eles. Se eles querem sliders eu uso uma consulta simples usando a classe WP_Query:

<?php

// Setup arguments.
$args = array(
    // Get the "slider" post type.
    'post_type' => 'slider',
    // Get a specific slider category.
    'category_name' => 'home-slides',
    // Get all slides and don't paginate.
    'nopaging' => true
);

// Instantiate new query instance.
$my_query = new WP_Query( $args );

?>

O argumento de 'cat' pode ser usado para recuperar slides de categorias diferentes, assim você pode separar grupos de slide e usar vários slides em várias páginas. Se você vai usar slider apenas em seu site, você pode excluir essa linha e você está pronto para usar.

Exemplo #5: Uma Citação Aleatória na Barra Lateral

Se você está interessado em literatura ou religião, convém ter algumas das suas citações favoritas na barra lateral — isso não é um desperdício de espaço se você tem um propósito. Então, se você vai listar uma citação aleatória na barra lateral em cada exibição da página, você pode usar o seguinte trecho de código para criar um tipo de post e usar a seguinte consulta para criar um loop em sua barra lateral:

<?php

/* 
 * Create new post type called "Quotes"
 * (refer to the `register_post_type` function to
 * learn more about creating custom post types).
 */
function quote_post_type() {
    
    $args = array(
        'label' => 'Quotes',
        'public' => true
    );
    
    register_post_type( 'quotes', $args );
}

add_action( 'init', 'quote_post_type' );

// Setup arguments.
$args = array(
    // Get the "quotes" psot type.
    'post_type' => 'quotes',
    // Randomize the order.
    'orderby' => 'rand',
    // Get only one item.
    'posts_per_page' => 1,
);

// Instantiate new query instance.
$my_query = new WP_Query( $args );

?>

Uma Solução Fácil e Elegante.

Exemplo #6: Listando Produtos Entre Uma Faixa de Preço

Eu encontrei este exemplo na Scribu.net e devo dizer é o melhor truque de WP_Query neste tutorial. É um pouco mais técnico do que os outros porque ele pode ser aplicado a um site de comércio eletrônico alimentado por WordPress neste contexto.

Aqui está o trecho de código que você vai usar se você quiser listar itens de um tipo de post personalizado "Product" e filtrar os resultados com os campos personalizados "price":

<?php

// Source: http://scribu.net/wordpress/advanced-metadata-queries.html

// Setup arguments.
$args = array(
    // Get the "product" post type.
    'post_type' => 'product',
    // Setup the "meta query".
    'meta_query' => array(
        array(
            // Get the "price" custom field.
            'key' => 'price',
            // Set the price values.
            'value' => array( 100, 200 ),
            // Set the compare operator.
            'compare' => 'BETWEEN',
            // Only look at numeric fields.
            'type' => 'numeric',
        )
    )
);

// Instantiate new query instance.
$my_query = new WP_Query( $args );

?>

Um grande parabéns a Silviu-Cristian Burca!

Exemplo #7: Um Shortcode Para Incorporar Posts Dentro de Posts

Aqui está um divertido exercício — e teremos de usar a API de Shortcode também! Neste exemplo, vamos criar um shortcode que pode incorporar um post dentro de um post. (Eu mal consigo me conter para nomear o shortcode como [postception].) No trecho de código a seguir criamos uma função de shortcode que nos permite incorporar posts (ou qualquer post personalizado) e nos permite escolher se desejamos mostrar o post completo ou apenas um resumo:

<?php

/*
 * Usage:
 *
 * [embed_post slug="my-post"]
 * [embed_post slug="my-post" full="false"]
 * [embed_post type="movie" slug="inception"]
 */

function tutsplus_embedded_post_shortcode( $attributes ) {

    // Extract shortcode attributes.
    extract(
        shortcode_atts(
            array(
                'type' => 'post',
                'slug' => '',
                'full' => true
            ),
            $attributes
        )
    );

    // Setup arguments.
    $args = array(
        // Get post type ("post" by default).
        'post_type' => $type,
        // Get post by slug.
        'name' => $slug
    );

    // Instantiate new query instance.
    $my_query = new WP_Query( $args );

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

        // Begin generating markup.
        $output = '<section class="embedded-post">';

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

            $my_query->the_post();

            // Add title to output.
            $output .= '<h2 class="embedded-post-title">';
                $output .= get_the_title();
            $output .= '</h2>';

            // Get full post if `$full` is true, otherwise, show the get excerpt
            if ( 'true' === $full ) {

                // Add full content to output.
                $output .= '<div class="embedded-post-content">';
                    $output .= get_the_content();
                $output .= '</div>';

            } else {

                // Add excerpt to output.
                $output .= '<div class="embedded-post-excerpt">';
                    $output .= get_the_excerpt();
                    $output .= '&hellip; <a href="' . get_permalink() . '">' . __( 'See full post', 'tutsplus' ) . ' &raquo;</a>';
                $output .= '</div>';

            }

        }

        // End generating markup.
        $output .= '</section>';

    } else {

        // Output message to let user know that no posts were found.
        $output = '<section class="embedded-post-error">';
            $output .= '<p>' . __( 'No posts found.', 'tutsplus' ) . '</p>';
        $output .= '</section>';

    }

    wp_reset_postdata();

    return $output;

}

add_shortcode( 'embed_post', 'tutsplus_embedded_post_shortcode' );

?>

Exemplo #8: Lista de Posts Agendados Atuais (Com Resumos Opcionais)

Aqui vai uma idéia: por que você não exibi algumas "espreitadelas" de seus próximos posts para seus visitantes? Você pode usar a seguinte função para listar seus posts agendadas com ou sem resumos após os títulos:

<?php

/*
 * Usage with Excerpts:
 *
 * <?php echo tutsplus_show_drafts(); ?>
 *
 * Usage without Excerpts:
 *
 * <?php echo tutsplus_show_drafts( false ); ?>
 */

function tutsplus_show_drafts( $show_excerpts = true ) {

    // Setup arguments.
    $args = array(
        'post_status' => 'pending',
        'nopaging' => true
    );

    // Instantiate new query instance.
    $my_query = new WP_Query( $args );

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

        // Begin generating markup.
        $output = '<section class="pending-posts">';

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

            $my_query->the_post();

            // Output draft post title and excerpt (if enabled).
            $output .= '<div class="pending">';
                $output .= '<h3 class="pending-title">' . get_the_title() . '</h3>';
                    $output .= get_the_title();
                $output .= '</h3>';

                if ( $show_excerpts ) {

                    $output .= '<div class="pending-excerpt">';
                        $output .= get_the_excerpt();
                    $output .= '</div>';

                }

            $output .= '</div>';

        }

        // End generating markup.
        $output .= '</section>';

    } else {

        // Let user know that nothing was found.
        $output = '<section class="drafts-error">';
            $output .= '<p>' . __( 'Nothing found', 'tutsplus' ) . '</p>';
        $output .= '</section>';

    }

    wp_reset_postdata();

    return $output;

}

?>

Exemplo #9: "Post de Um Ano Atrás - Hoje"

Se seu blog tem mais de um ano e seu conteúdo é atemporal (ou seja, que tanto uma pessoa de 2015 e 2025 irá encontrar o artigo relevante), adicionando uma seção "Post de um ano atrás hoje" poderia levantar suas visualizações de página. Aqui está como fazer isso:

<?php

// Setup arguments.
$args = array(
    // Day (1 - 31).
    'day' => date( 'j' ),
    // Month (1 - 12).
    'monthnum' => date( 'n' ),
    // Year (minus 1).
    'year' => date( 'Y' ) - 1,
    // Show only one post.
    'posts_per_page' => 1
);

// Instantiate new query instance.
$my_query = new WP_Query( $args );

?>

Use essa consulta para construir um loop que exibe um único post do ano passado.

Exemplo #10: Mostrar os Filhos da Página Atual

Você não tem nada que não seja títulos ou sub-páginas para colocar dentro de suas páginas "Serviços", ou "Meus Portfólios"? Talvez um parágrafo de introdução, mas você está certo que essas páginas estão condenadas a serem "placeholders". Ainda assim, é uma boa idéia colocar sub-páginas lá — talvez uma grade de miniaturas quadradas e títulos abaixo. Vamos ver como devemos fazer a consultar, sugiro criar uma página de template para isso:

<?php

$current_page_id = get_the_ID();

// Setup arguments.
$args = array(
    // Get children of current page.
    'parent' => $current_page_id,
    // Disable pagination.
    'nopaging' => true
);

// Instantiate new query instance.
$my_query = new WP_Query( $args );

?>

Encerrando

Espero que tenha gostado destes exemplos tanto quanto eu gostei de escrevê-los. Dei uma atenção especial para dar exemplos variados para ser divertido e para estimular a sua criatividade.

Se você pensou em exemplos melhores ao ler os meus, ou tiver dúvidas, não hesite em se atirar em um comentário abaixo. E se você gostou do artigo, não se esqueça de compartilhar com seus amigos!

Na próxima parte, vamos falar sobre WP_User_Query uma irmã classes de WP_Query. Até lá!

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

1	<?php
2
3	/*
4	* Usage:
5	*
6	* [embed_post slug="my-post"]
7	* [embed_post slug="my-post" full="false"]
8	* [embed_post type="movie" slug="inception"]
9	*/
10
11	function tutsplus_embedded_post_shortcode( $attributes ) {
12
13	// Extract shortcode attributes.
14	extract(
15	shortcode_atts(
16	array(
17	'type' => 'post',
18	'slug' => '',
19	'full' => true
20	),
21	$attributes
22	)
23	);
24
25	// Setup arguments.
26	$args = array(
27	// Get post type ("post" by default).
28	'post_type' => $type,
29	// Get post by slug.
30	'name' => $slug
31	);
32
33	// Instantiate new query instance.
34	$my_query = new WP_Query( $args );
35
36	// Check that we have query results.
37	if ( $my_query->have_posts() ) {
38
39	// Begin generating markup.
40	$output = '<section class="embedded-post">';
41
42	// Start looping over the query results.
43	while ( $my_query->have_posts() ) {
44
45	$my_query->the_post();
46
47	// Add title to output.
48	$output .= '<h2 class="embedded-post-title">';
49	$output .= get_the_title();
50	$output .= '</h2>';
51
52	// Get full post if `$full` is true, otherwise, show the get excerpt
53	if ( 'true' === $full ) {
54
55	// Add full content to output.
56	$output .= '<div class="embedded-post-content">';
57	$output .= get_the_content();
58	$output .= '</div>';
59
60	} else {
61
62	// Add excerpt to output.
63	$output .= '<div class="embedded-post-excerpt">';
64	$output .= get_the_excerpt();
65	$output .= '… <a href="' . get_permalink() . '">' . __( 'See full post', 'tutsplus' ) . ' »</a>';
66	$output .= '</div>';
67
68	}
69
70	}
71
72	// End generating markup.
73	$output .= '</section>';
74
75	} else {
76
77	// Output message to let user know that no posts were found.
78	$output = '<section class="embedded-post-error">';
79	$output .= '<p>' . __( 'No posts found.', 'tutsplus' ) . '</p>';
80	$output .= '</section>';
81
82	}
83
84	wp_reset_postdata();
85
86	return $output;
87
88	}
89
90	add_shortcode( 'embed_post', 'tutsplus_embedded_post_shortcode' );
91
92	?>

1	<?php
2
3	/*
4	* Usage with Excerpts:
5	*
6	* <?php echo tutsplus_show_drafts(); ?>
7	*
8	* Usage without Excerpts:
9	*
10	* <?php echo tutsplus_show_drafts( false ); ?>
11	*/
12
13	function tutsplus_show_drafts( $show_excerpts = true ) {
14
15	// Setup arguments.
16	$args = array(
17	'post_status' => 'pending',
18	'nopaging' => true
19	);
20
21	// Instantiate new query instance.
22	$my_query = new WP_Query( $args );
23
24	// Check that we have query results.
25	if ( $my_query->have_posts() ) {
26
27	// Begin generating markup.
28	$output = '<section class="pending-posts">';
29
30	// Start looping over the query results.
31	while ( $my_query->have_posts() ) {
32
33	$my_query->the_post();
34
35	// Output draft post title and excerpt (if enabled).
36	$output .= '<div class="pending">';
37	$output .= '<h3 class="pending-title">' . get_the_title() . '</h3>';
38	$output .= get_the_title();
39	$output .= '</h3>';
40
41	if ( $show_excerpts ) {
42
43	$output .= '<div class="pending-excerpt">';
44	$output .= get_the_excerpt();
45	$output .= '</div>';
46
47	}
48
49	$output .= '</div>';
50
51	}
52
53	// End generating markup.
54	$output .= '</section>';
55
56	} else {
57
58	// Let user know that nothing was found.
59	$output = '<section class="drafts-error">';
60	$output .= '<p>' . __( 'Nothing found', 'tutsplus' ) . '</p>';
61	$output .= '</section>';
62
63	}
64
65	wp_reset_postdata();
66
67	return $output;
68
69	}
70
71	?>