Maitriser WP_Query : Utilisation de la boucle

French (Français) translation by Jean-Frédéric Barré (you can also view the original English article)

Comme nous l'avons vu dans la partie précédente, la classe WP_Query possède quatre éléments principaux :

les arguments de la requête, qui utilisent des paramètres que nous allons voir en détails dans la suite de cette série
la requête elle même
la boucle, qui va afficher les contenu des billets, les titres ou tout autres éléments du billet
la fin de boucle qui va fermer les "if" et "while" et remettre à zéro la boucle.

Dans ce tutoriel, je vais vous montrer les deux façons principale d' utiliser la boucle avec WP_Query et comment utilise plusieurs boucle sur une même page.

Où utiliser la boucle ?

Sans une boucle, rien ne s'affichera sur votre page. Après que WordPress ai lancé la requête principale, il faut lui indiquer quoi afficher dans tout ce tas de données. C'est là que la boucle intervient.

La boucle vient donc après votre requête, elle utilise trois marqueurs :

if( $query->have_posts() ) vérifie s'il y a bien des billets.
while( $query->have_posts() ) répète la boucle pour chacun des billets, jusqu'à ce qu'il n'y ait plus de billets à afficher.
$query->the_post() permet d'accéder à ces billets.

C'est donc ici que la boucle utilise la classe WP_Query.

<?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();

?>

Après la boucle, ce qu'il reste à faire c'est "rangé" la requête avec wp_reset_postdata().

La structure de la boucle

La manière dont est structuré votre boucle va dépendre des données que vous voulez afficher. Voici l'exemple d'une boucle affichant le titre du billet, l'image mise en avant et le résumé. Il est probable que vous utilisiez cette boucle sur vos pages archives.

<?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();

        ?>

        <article id="post-<?php the_ID(); ?>" <?php post_class( 'left' ); ?>>
            <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
                <?php post_thumbnail( 'thumbnail' );?>
            </a>
            <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
                <?php the_title(); ?>
            </a>
            <?php the_excerpt(); ?>
        </article>

        <?php

    }

}

// Restore original post data.
wp_reset_postdata();

?>

Cette boucle affiche exactement ce que nous avons décrit précédemment : image à la une, titre et résumé.

Approfondissons la boucle : vérifier le contenu

Vous pouvez parfois avoir envie d'ajouter une ligne de texte avant la liste des billets ou bien vous pouvez avoir envie d'inclure cette liste dans un conteneur particulier. Si vous ajouté simplement cet élément avant la boucle, il sera ajouté de manière systématique, même s'il n'y a pas de billets à afficher.

Pour régler ce problème, il suffit de placer notre élément dans la boucle if.

<?php

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

// Custom query.
$query = new WP_Query( $args );

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

    
    echo '<section class="clear">';
        echo '<h2>' . __( 'Heading', 'tutsplus' ) . '</h2>';
    
        // Start looping over the query results.
        while ( $query->have_posts() ) {
    
            $query->the_post();
    
            ?>
    
            <article id="post-<?php the_ID(); ?>" <?php post_class( 'left' ); ?>>
                <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
                    <?php post_thumbnail( 'thumbnail' );?>
                </a>
                <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
                    <?php the_title(); ?>
                </a>
                <?php the_excerpt(); ?>
            </article>
    
            <?php
    
        }
    
    echo '</section>';

}

// Restore original post data.
wp_reset_postdata();

?>

Ici vous pouvez voir que je vérifie qu'il y a bien des billets à afficher et, s'il y en a, j'ajoute un conteneur et une phrase.

C'est aussi très pratique si vous voulez afficher le contenu de votre requête sous forme de liste. Disons que je veux afficher la liste de tous les billets d'une catégorie particulière. L'élément ul ne se trouve pas dans la boucle car il n'est pas attaché à un billet en particulier. Je veux le voir uniquement s'il y a des billets. J'utilise donc ceci :

<?php

$args = array(
    'category_name' => 'category-slug',
    'post_type' => 'post'
);

// Custom query.
$query = new WP_Query( $args );

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

    echo '<ul class="category posts">';

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

            $query->the_post();

            ?>

            <li <?php post_class( 'left' ); ?>>
                <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
                    <?php the_title(); ?>
                </a>
            </li>

            <?php
    
        }

    echo '</ul>';

}

// Restore original post data.
wp_reset_postdata();

?>

Ceci vérifie que la requête retourne des billets et si et seulement si c'est le cas, alors il ouvre un élément ul et y lance la boucle.

Lancer des boucles supplémentaires

Il faut absolument comprendre que si vous utilisez WP_Query pour lancer plusieurs boucles, vous devez remettre à zéro la requête avant de lancer une nouvelle instance de WP_Query. Il en va ainsi car chacune des boucles va afficher des billets en fonctions de différents arguments.

Cet exemple affiche le résumé et l'image à la une pour le premier billet et ensuite uniquement le titre des billets suivants :

<?php

// First query arguments.
$args1 = array(
    'post_type' => 'post',
    'posts_per_page' => '1'
);

// First custom query.
$query1 = new WP_Query( $args1 );

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

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

        $query1->the_post();

        ?>

        <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
            <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
                <?php post_thumbnail( 'thumbnail' );?>
            </a>
            <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
                <?php the_title(); ?>
            </a>
            <?php the_excerpt(); ?>
        </article>

        <?php

    }

}

// Restore original post data.
wp_reset_postdata();

// Second query arguments.
$args2 = array(
    'offset' => '1',
    'post_type' => 'post'
);

// Second custom query.
$query2 = new WP_Query( $args2 );

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

    echo '<ul class="more-posts">';
    
        // Start looping over the query results.
        while ( $query2->have_posts() ) {

            $query2->the_post();
    
            ?>

            <li <?php post_class(); ?>>
                <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
                    <?php the_title(); ?>
                </a>
            </li>
    
            <?php
    
        }
    
    echo '</ul>';

}

// Restore original post data.
wp_reset_postdata();

?>

J'utilise ici deux arguments essentiels :

'posts_per_page' => '1' , utilisé avec la première requête, il affiche le billet le plus récent.
'offset' = '1' , utilisé dans la seconde boucle, il exclu le premier billet afin d'éviter d'afficher deux fois le même contenu.
Comme vous pouvez le constater dans l'exemple ci-dessus, la boucle est légèrement différente pour chacune des requêtes. La première affiche l'image à la une, le titre et le résumé alors que la seconde vérifie que la requête retourne bien des billets et, si c'est le cas, ouvre un élément ul et y intègre le titre avec lien dans un élément li, et ceci pour chacun des billets retourné par la requête.

Vous remarquerez aussi que j'utilise wp_reset_postdata() après chacune des boucles. Si je n'avais pas fait cela, la seconde boucle continuerait de renvoyer les données de la première.

Récapitulatif :

Sans une boucle, WP_Query ne sert pas à grand chose. La boucle est le code que vous utilisez pour afficher les données renvoyées par la requête de WordPress.

Comme nous venons de le voir, l'utilisation de la boucle peut varier en fonction des circonstances. Une boucle simple va afficher tous les billets dans l'ordre que vous aurez spécifié via les arguments de la requête (par date en ordre descendant par défaut). Si vous séparé if( $query->have_posts() ) et while( $query->have_posts() ), vous pourrez ajouter du code supplémentaire en dehors de la boucle mais uniquement si votre requête renvoie des données. Pour finir, en spécifiant des arguments et en utilisant wp_reset_postdata() après chacune des boucles, vous pouvez utiliser WP_Query plusieurs fois pour créer des boucles multiples sur une seule et même page.