() translation by (you can also view the original English article)
Como foi esboçado na introdução a esta série, a classe WP_Query tem quatro elementos principais:
- os argumentos para a consulta, utilizando parâmetros que serão abordados em detalhes nesta série
- a consulta em si
- o loop, que vai exibir o conteúdo de saída, como títulos ou o que você desejá exibir
- terminações: fechando os if e while tags e resetando dados post
Neste tutorial eu vou mostrar como usar o loop com WP_Query, incluindo as duas principais maneiras de estruturar o seu loop e como usar multiplos loops.
Quando o loop se encaixa
Sem um loop, nada será exibido na sua página. Depois que o Wordpress executar a consulta, usando os argumentos que você definiu, ele precisara dizer o que deve ser exibido através dos dados que foram percorridos. Este é o lugar onde o loop entra.
O loop vem após a sua consulta, e ele usa três tags:
-
if( $query->have_posts() )verifica se existem posts. -
while( $query->have_posts() )enquanto houver posts para retornar, repete o loop para cada post.
-
$query->the_post()acessa um post específico.
Portanto, este é o lugar em que o loop se encaixa na classe WP_Query:
1 |
<?php
|
2 |
|
3 |
$args = array( |
4 |
// Arguments for your query.
|
5 |
);
|
6 |
|
7 |
// Custom query.
|
8 |
$query = new WP_Query( $args ); |
9 |
|
10 |
// Check that we have query results.
|
11 |
if ( $query->have_posts() ) { |
12 |
|
13 |
// Start looping over the query results.
|
14 |
while ( $query->have_posts() ) { |
15 |
|
16 |
$query->the_post(); |
17 |
|
18 |
// Contents of the queried post results go here.
|
19 |
|
20 |
}
|
21 |
|
22 |
}
|
23 |
|
24 |
// Restore original post data.
|
25 |
wp_reset_postdata(); |
26 |
|
27 |
?>
|
Depois de executar o loop, tudo o que resta a fazer é arrumar as coisas usando wp_reset_postdata().
Estrutura do Loop
A forma como o loop está estruturado vai depender dos dados que você deseja exibir do seu post. Aqui está um exemplo de loop que exibi o título do post, a imagem de destaque e um resumo. Você usaria um loop como este em uma página de arquivo.
1 |
<?php
|
2 |
|
3 |
$args = array( |
4 |
// Arguments for your query.
|
5 |
);
|
6 |
|
7 |
// Custom query.
|
8 |
$query = new WP_Query( $args ); |
9 |
|
10 |
// Check that we have query results.
|
11 |
if ( $query->have_posts() ) { |
12 |
|
13 |
// Start looping over the query results.
|
14 |
while ( $query->have_posts() ) { |
15 |
|
16 |
$query->the_post(); |
17 |
|
18 |
?>
|
19 |
|
20 |
<article id="post-<?php the_ID(); ?>" <?php post_class( 'left' ); ?>> |
21 |
<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>"> |
22 |
<?php post_thumbnail( 'thumbnail' );?> |
23 |
</a>
|
24 |
<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>"> |
25 |
<?php the_title(); ?> |
26 |
</a>
|
27 |
<?php the_excerpt(); ?> |
28 |
</article>
|
29 |
|
30 |
<?php
|
31 |
|
32 |
}
|
33 |
|
34 |
}
|
35 |
|
36 |
// Restore original post data.
|
37 |
wp_reset_postdata(); |
38 |
|
39 |
?>
|
Este loop exibe exatamente o que eu descrevi acima: a imagem de destaque, título e resumo.
Extendendo o seu Loop: Verificando o Conteúdo
Mas talvez você quisesse ter adicionado um título antes da lista dos posts, ou quisesse ter colocado todos eles dentro de um elemento de conteúdo. Se você simplesmente tivesse feito isto antes, o seu loop teria sido exibido independentemente se a consulta retornasse algum dado, o que significa que você poderia ter um título sem nada em baixo, ou alguma marcação desnecessária.
Isso é muito fácil de se contornar, colocando o elemento delimitador ou o título dentro de seu tag if:
1 |
<?php
|
2 |
|
3 |
$args = array( |
4 |
// Arguments for your query.
|
5 |
);
|
6 |
|
7 |
// Custom query.
|
8 |
$query = new WP_Query( $args ); |
9 |
|
10 |
// Check that we have query results.
|
11 |
if ( $query->have_posts() ) { |
12 |
|
13 |
|
14 |
echo '<section class="clear">'; |
15 |
echo '<h2>' . __( 'Heading', 'tutsplus' ) . '</h2>'; |
16 |
|
17 |
// Start looping over the query results.
|
18 |
while ( $query->have_posts() ) { |
19 |
|
20 |
$query->the_post(); |
21 |
|
22 |
?>
|
23 |
|
24 |
<article id="post-<?php the_ID(); ?>" <?php post_class( 'left' ); ?>> |
25 |
<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>"> |
26 |
<?php post_thumbnail( 'thumbnail' );?> |
27 |
</a>
|
28 |
<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>"> |
29 |
<?php the_title(); ?> |
30 |
</a>
|
31 |
<?php the_excerpt(); ?> |
32 |
</article>
|
33 |
|
34 |
<?php
|
35 |
|
36 |
}
|
37 |
|
38 |
echo '</section>'; |
39 |
|
40 |
}
|
41 |
|
42 |
// Restore original post data.
|
43 |
wp_reset_postdata(); |
44 |
|
45 |
?>
|
Aqui você pode ver, verifiquei se existem posts retornados em minha consulta e se houver abri um elemento de conteudo e acrescentei um título.
Isso também é útil se você quiser exibir os resultados da consulta como uma lista. Vamos dizer que eu quero criar uma lista de todos os posts de uma determinada categoria. O elemento ul não está dentro do meu loop, uma vez que não diz respeito a um post específico, mas eu quero apenas
exibir se existir posts. Então, eu faço o seguinte:
1 |
<?php
|
2 |
|
3 |
$args = array( |
4 |
'category_name' => 'category-slug', |
5 |
'post_type' => 'post' |
6 |
);
|
7 |
|
8 |
// Custom query.
|
9 |
$query = new WP_Query( $args ); |
10 |
|
11 |
// Check that we have query results.
|
12 |
if ( $query->have_posts() ) { |
13 |
|
14 |
echo '<ul class="category posts">'; |
15 |
|
16 |
// Start looping over the query results.
|
17 |
while ( $query->have_posts() ) { |
18 |
|
19 |
$query->the_post(); |
20 |
|
21 |
?>
|
22 |
|
23 |
<li <?php post_class( 'left' ); ?>> |
24 |
<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>"> |
25 |
<?php the_title(); ?> |
26 |
</a>
|
27 |
</li>
|
28 |
|
29 |
<?php
|
30 |
|
31 |
}
|
32 |
|
33 |
echo '</ul>'; |
34 |
|
35 |
}
|
36 |
|
37 |
// Restore original post data.
|
38 |
wp_reset_postdata(); |
39 |
|
40 |
?>
|
Isto verifica se a consulta tem buscado quaisquer posts e se caso sim, ele abre o elemento da ul e em seguida, executa o loop.
Executando Múltiplos Loops
Tome cuidado quando estiver usando o WP_Query para executar mais de um loop, você precisará resetar os dados do post para depois iniciar uma segunda consulta WP_Query. Isso ocorre porque cada um de seus loops terão saída de dados com base em diferentes argumentos.
Este exemplo exibi o resumo e imagem de destaque para o primeiro post e em seguida, apenas o título de cada post subsequente:
1 |
<?php
|
2 |
|
3 |
// First query arguments.
|
4 |
$args1 = array( |
5 |
'post_type' => 'post', |
6 |
'posts_per_page' => '1' |
7 |
);
|
8 |
|
9 |
// First custom query.
|
10 |
$query1 = new WP_Query( $args1 ); |
11 |
|
12 |
// Check that we have query results.
|
13 |
if ( $query1->have_posts() ) { |
14 |
|
15 |
// Start looping over the query results.
|
16 |
while ( $query1->have_posts() ) { |
17 |
|
18 |
$query1->the_post(); |
19 |
|
20 |
?>
|
21 |
|
22 |
<article id="post-<?php the_ID(); ?>" <?php post_class(); ?>> |
23 |
<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>"> |
24 |
<?php post_thumbnail( 'thumbnail' );?> |
25 |
</a>
|
26 |
<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>"> |
27 |
<?php the_title(); ?> |
28 |
</a>
|
29 |
<?php the_excerpt(); ?> |
30 |
</article>
|
31 |
|
32 |
<?php
|
33 |
|
34 |
}
|
35 |
|
36 |
}
|
37 |
|
38 |
// Restore original post data.
|
39 |
wp_reset_postdata(); |
40 |
|
41 |
// Second query arguments.
|
42 |
$args2 = array( |
43 |
'offset' => '1', |
44 |
'post_type' => 'post' |
45 |
);
|
46 |
|
47 |
// Second custom query.
|
48 |
$query2 = new WP_Query( $args2 ); |
49 |
|
50 |
// Check that we have query results.
|
51 |
if ( $query2->have_posts() ) { |
52 |
|
53 |
echo '<ul class="more-posts">'; |
54 |
|
55 |
// Start looping over the query results.
|
56 |
while ( $query2->have_posts() ) { |
57 |
|
58 |
$query2->the_post(); |
59 |
|
60 |
?>
|
61 |
|
62 |
<li <?php post_class(); ?>> |
63 |
<a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>"> |
64 |
<?php the_title(); ?> |
65 |
</a>
|
66 |
</li>
|
67 |
|
68 |
<?php
|
69 |
|
70 |
}
|
71 |
|
72 |
echo '</ul>'; |
73 |
|
74 |
}
|
75 |
|
76 |
// Restore original post data.
|
77 |
wp_reset_postdata(); |
78 |
|
79 |
?>
|
Eu usei dois argumentos-chave aqui:
-
'posts_per_page' => '1', usado com a primeira consulta, produz apenas o post mais recente. -
'offset' = '1', usado com a segunda consulta, salta para a primeiro post, garantindo que não é repetido na lista abaixo. - Como você pode ver no código acima, o loop é um pouco diferente para cada consulta. Na primeira saída exibi uma imagem de destaque, título e resumo, enquanto a segunda verifica se a consulta retornou os posts se sim, abri o elemento
ulque junta cada título de post no elementolicom um link para sua página.
Você também vai notar que eu usei wp_reset_postdata() depois de ambos os loops. Se eu não tivesse feito isso, o segundo loop exibiria dados do primeiro loop.
Resumo
Sem um loop, WP_Query realmente não faz muito coisa. O loop é o código que você usa para exibir os dados que o WordPress tem buscado a partir do banco de dados com base em seus argumentos de consulta.
Como já demonstrado, existem algumas variações de loop. Um loop simples irá apenas exibir todos os posts na ordem que você especificou em seus argumentos de consulta (ou por data, em ordem decrescente por padrão). Se você separar if( $query->have_posts() ) e while( $query->have_posts() ), você pode inserir uma marcação adicional fora do seu loop, mas apenas se sua consulta retorna dados. E finalmente, especificando argumentos alternativos e usando wp_reset_postdata() depois de cada loop, você pode usar WP_Query mais de uma vez para criar múltiplos loops em sua página.
Seja o primeiro a saber sobre novas traduções–siga @tutsplus_pt no Twitter!
