Créer une boucle personnalisée permet d’afficher des articles ou des pages statiques à n’importe quel endroit d’un site et suivant des critères totalement indépendants de la boucle principale de WordPress.

La classe WP_Query et la fonction get_posts() permettent de sélectionner des articles ou des pages en fonction des critères et de l’ordre choisis par le développeur (catégories, étiquettes, auteurs, statuts, dates, méta données…). 

La classe WP_Query

La classe WP_Query gère les requêtes à la Base de Données WordPress afin d’y retrouver les données sur les articles et les pages répondants aux critères de sélection. Elle permet de créer des boucles en fonction d’un paramétrage spécifique, indépendant de la boucle principale.

Les paramètres disponibles pour les requêtes sont ceux décrits pour le crochet pre_get_posts ou la fonction query_posts().

Le code ci-dessous permet d’afficher le titre des pages publiées sur le site avant d’afficher la boucle principale :

//	affichage des titres des pages
$wpdf_args = array(
	'post_type'  => 'page'
	);
$wpdf_query = new WP_Query( $wpdf_args );
if ( $wpdf_query->have_posts() ) :
	while ( $wpdf_query->have_posts() ) : $wpdf_query->the_post();
		echo get_the_title().'<br/>';
	endwhile;
endif;
wp_reset_postdata();			

//	affichage de la boucle principale (non modifié)
if ( have_posts() ) :
	// Start the Loop.
	while ( have_posts() ) : the_post();
		get_template_part( 'content', get_post_format() );
	endwhile;
....

Voici l’affichage obtenu, avec :

• boucle personnalisée : les titres des pages statiques publiées,
• boucle principale : les derniers articles publiés (boucle principale ‘standard’ de la page d’accueil).

Commentaires :

• la méthode « new » appliquée à la classe WP_Query permet de créer une nouvelle requête sur la Base de Données,
• la méthode « new » accepte un tableau de paramètres pour définir les critères de la requête (certains paramètres pouvant être des tableaux),
• les fonctions « have_posts() » et « the_posts » doivent être appliquées au nouvel objet requête : $wpdf_query->have_posts(),
• les fonctions telles que « the_title(), « the_author », « the_content »… s’appliquent sur l’article ou la page chargée par le dernier appel à la fonction « the_post() »; la documentation WordPress (codex) précise que ces fonctions sont à utiliser « dans la boucle » (within the loop),

• la fonction wp_reset_postdata() permet de restaurer l’état de la boucle principale tel qu’il était en début d’affichage de la page courante.

Multi-paramétrage d’une requête

Enregistrer un article à l’état de brouillon :

Planifier la publication d’un article à une date ultérieure :

Insérer le code suivant dans le fichier index.php :

//	affichage de la boucle personnalisée
$wpdf_args = array(
	'post_status' => array( 'draft', 'future', 'publish' ),
	'cat' => '21',
	'posts_per_page' => '5',
	'orderby' => array( 'title' => 'DESC', 'name' => 'ASC' )
	);
$wpdf_query = new WP_Query( $wpdf_args );
if ( $wpdf_query->have_posts() ) :
	while ( $wpdf_query->have_posts() ) : $wpdf_query->the_post();
		echo get_the_title().'    ('.get_permalink().')<br/>';
	endwhile;
endif;
wp_reset_postdata();			

//	affichage de la boucle principale (non modifiée)
if ( have_posts() ) :
...

Voici l’affichage obtenu :

Regardons le paramétrage de la boucle personnalisée :

•  ‘post_status’ => array( ‘draft’, ‘future’, ‘publish‘ ) ⇒ prendre en compte les articles à l’état de brouillon ou planifiés ou publiés
• ‘cat‘ => ’21’ ⇒ prendre uniquement en compte les articles de la catégorie d’identifiant ’21’
• ‘posts_per_page‘ => ‘5’ ⇒ afficher au plus 5 articles par exécution de la boucle personnalisée
• ‘orderby’ => array( ‘title’ => ‘DESC’, ‘name’ => ‘ASC’ ) ⇒ afficher en triant sur le titre des articles en ordre descendant  puis sur le ‘nom’ comme critère secondaire en ordre ascendant.

Pour chaque article sélectionné, on affiche son titre [echo get_the_title()] puis son ‘permalien’ [get_permalink()] .

Voici ce qu’on obtient en affichant 10 articles [ ‘posts_per_page’ => ’10’ ] et en inversant les ordres de tri  [‘orderby’ => array( ‘title’ => ‘ASC’, ‘name’ => ‘DESC’ ] :

Sélection sur une période de temps

Insérer le code suivant dans le fichier index.php :

//	affichage de la boucle personnalisée
$wpdf_args = array(
	'date_query' => array(
		array(
			'after'     => 'January 1st, 2015',
			'before'    => array(
				'year'  => 2015,
				'month' => 4,
				'day'   => 10,
			),
			'inclusive' => true,
		),
	),
	'posts_per_page' => -1,
);

$wpdf_query = new WP_Query( $wpdf_args );
if ( $wpdf_query->have_posts() ) :
	while ( $wpdf_query->have_posts() ) : $wpdf_query->the_post();
		echo get_the_title().' ('.get_the_date().')<br/>';
	endwhile;
endif;
wp_reset_postdata();			

//	affichage de la boucle principale (non modifiée)
if ( have_posts() ) :
...

Voici l’affichage obtenu :

La boucle personnalisée affiche tous les articles entre le 1er janvier 2015 [ ‘after’     => ‘January 1st, 2015’, ] et le 10 avril 2015 [ ‘before’ => array( ‘year’ => 2015, ‘month’ => 4, ‘day’ => 10,), ] les deux dates étant comprises [ ‘inclusive’ => true, ].

Le codex décrit le paramétrage disponible pour gérer les périodes de temps.

Remarquons que des paramètres par défaut sont appliqués : ordre descendant sur les dates de publication, toutes les catégories et étiquettes, seulement les articles publiés…

Sélection sur les champs personnalisés

Insérer le code suivant dans le fichier index.php :

//	affichage de la boucle personnalisée
$wpdf_args = array(
	'cat'	=> '21',
	'meta_query' => array(
			array(
			'key'     => 'trier',
			'value'   => 'F',
			'compare' => 'NOT LIKE',
		),
			array(
			'key' => 'ordre',
			'value'   => array( 10, 100 ),
			'type'    => 'numeric',
			'compare' => 'BETWEEN',
		),
	),
);
$wpdf_query = new WP_Query( $wpdf_args );
if ( $wpdf_query->have_posts() ) :
	while ( $wpdf_query->have_posts() ) : $wpdf_query->the_post();
		echo get_the_title().' ('.get_the_date().')<br/>';
	endwhile;
endif;
wp_reset_postdata();

Voici l’affichage obtenu :

L’article 4 est le seul à répondre aux trois conditions posées dans le paramétrage de la boucle personnalisée :

• appartenir à la catégorie d’identifiant ’21’ [ ‘cat’ => ’21’ ],
• avoir un champ personnalisé de nom « trier » avec un contenu différent de ‘F’ [‘meta_query’ => array( array( ‘key’ => ‘trier’, ‘value’ => ‘F’, ‘compare’ => ‘NOT LIKE’, ) ]
• avoir un champ personnalisé  de nom « ordre » avec une valeur comprise entre 10 et 20 [‘meta_query’ => array( array( ‘key’ => ‘ordre’, ‘value’ => array( 10, 100 ), ‘type’ => ‘numeric’,  ‘compare’ => ‘BETWEEN’,) ]

Voici les champs personnalisés de l’article 4 :

Champs personnalisés avec clauses

La version 4.2, publiée en avril 2015, a introduit la possibilité de réaliser des tris sur plusieurs champs personnalisés dans une même requête.

Modifier les articles 1 à 5 en affectant :

• dans le champ ‘trier’ : le numéro de l’article sous forme littérale (‘un’ pour l’article 1, ‘deux’ pour l’article 2…),
• dans le champ ‘ordre’ : ‘1’ pour les articles de numéro impair, ‘2’ pour les articles de numéro pair.

Voici les champs personnalisés de l’article 4 :

Insérer le code suivant dans le fichier index.php :

//	affichage de la boucle personnalisée
$wpdf_args = array(
	'cat'	=> '21',
	'meta_query' => array(
        'relation' => 'AND',
		'clause_ordre' => array(
			'key' => 'ordre',
			'value'   => array( 1, 2 ),
			'type'    => 'numeric',
			'compare' => 'BETWEEN',
		),
		'clause_trier' =>array(
			'key'     => 'trier',
			'value'   => 'F',
			'compare' => 'NOT LIKE',
		),
	),
	'orderby' => array (
		'clause_ordre' => 'ASC',
		'clause_trier' => 'DESC'
	)
);
$wpdf_query = new WP_Query( $wpdf_args );
if ( $wpdf_query->have_posts() ) :
	while ( $wpdf_query->have_posts() ) : $wpdf_query->the_post();
		echo get_the_title().' ('.get_the_date().')<br/>';
	endwhile;
endif;
wp_reset_postdata();	

//	affichage de la boucle principale (non modifiée)
if ( have_posts() ) :
...

Voici l’affichage obtenu :

• seuls sont sélectionnés les articles de la catégorie ’21’, dont le champ personnalisé « ordre » a une valeur comprise entre ‘1’ et ‘2’ et la valeur du champ « trier » est différente de ‘F’,
• le tri s’effectue d’abord sur le champ « ordre » en ordre ascendant : les articles de numéro impair (valeur = 1) apparaissent avant les articles de numéro pair (valeur = 2),
• le tri secondaire s’effectue sur le champ « trier » en ordre descendant : les articles sont triés ensuite sur la première lettre de leur libellé (Un avant Trois et Cinq, puis Quatre avant Deux).

La fonction get_posts()

get_posts() permet d’utiliser la classe WP Query au travers d’une fonction. Le codex décrit la fonction get_posts() (en anglais).

La fonction get_posts() renvoie un tableau d’objets décrivant les articles sélectionnés.

Utilisation de get_posts()

Insérer le code suivant dans le fichier index.php :

//	affichage de la boucle personnalisée
$wpdf_args = array(
	'cat' => '21',
	'orderby' => 'title',
	'post_status' => array ('publish', 'future'),
	'posts_per_page' => '-1',
	'order' => 'ASC'
);
$wpdf_posts = get_posts( $wpdf_args );
foreach ( $wpdf_posts as $un_article ) :
	echo ($un_article->post_title.'( ID = '.$un_article->ID.' )<br/>');
endforeach; 		

//	affichage de la boucle principale (non modifiée)
if ( have_posts() ) :

Voici l’affichage obtenu :

Tous les articles de la catégorie ’21’, publiés ou à publier sont sélectionnés et triés sur leur titre suivant l’ordre ascendant :

• ‘cat’ => ’21’ ⇒ sélectionner les articles de la catégorie dont l’identifiant est ’21’
• ‘orderby’ => ‘title’ ⇒trier suivant le titre
• ‘post_status’ => array (‘publish’, ‘future’) ⇒ sélectionner les articles publiés ou à publier
• ‘posts_per_page’ => ‘-1’ ⇒ sélectionner tous les articles répondant aux autres conditions
• ‘order’ => ‘ASC’ ⇒ trier en ordre ascendant (du plus ancien au plus récent)

Voici, en partie, ce que retourne la fonction get_posts() dans l’exemple ci-dessus :

array (size=7)
0 =>
object(WP_Post)[3835]
public ‘ID’ => int 2613
public ‘post_author’ => string ‘3’ (length=1)
public ‘post_date’ => string ‘2015-04-04 19:03:12’ (length=19)
public ‘post_date_gmt’ => string ‘2015-04-04 17:03:12’ (length=19)
public ‘post_content’ => string ‘Premier article de la catégorie démo’ (length=38)
public ‘post_title’ => string ‘article 1’ (length=9)
public ‘post_excerpt’ => string  » (length=0)
public ‘post_status’ => string ‘publish’ (length=7)
public ‘comment_status’ => string ‘open’ (length=4)
public ‘ping_status’ => string ‘closed’ (length=6)
public ‘post_password’ => string  » (length=0)
public ‘post_name’ => string ‘article-1’ (length=9)
public ‘to_ping’ => string  » (length=0)
public ‘pinged’ => string  » (length=0)
public ‘post_modified’ => string ‘2015-04-16 17:40:26’ (length=19)
public ‘post_modified_gmt’ => string ‘2015-04-16 15:40:26’ (length=19)
public ‘post_content_filtered’ => string  » (length=0)
public ‘post_parent’ => int 0
public ‘guid’ => string ‘http://localhost/demo/?p=2613’ (length=29)
public ‘menu_order’ => int 0
public ‘post_type’ => string ‘post’ (length=4)
public ‘post_mime_type’ => string  » (length=0)
public ‘comment_count’ => string ‘0’ (length=1)
public ‘filter’ => string ‘raw’ (length=3)
1 =>
object(WP_Post)[3860]
public ‘ID’ => int 2615
public ‘post_author’ => string ‘3’ (length=1)

Utilisation des « fonctions dans la boucle »

Les fonctions comme the_title(), the_content(), the_permalink()… doivent être utilisées dans une boucle WordPress. Pour les utiliser avec la fonction get_posts(), il est nécessaire de charger les objets WP Query, obtenus comme résultat de la fonction get_posts(), dans la variable globale $post.

Insérer le code suivant dans le fichier index.php :

//	affichage de la boucle personnalisée
$wpdf_args = array(
	'cat'	=> '21',
	'meta_query' => array(
		array(
			'key' => 'ordre',
			'value'   => array( 10, 100 ),
			'type'    => 'numeric',
			'compare' => 'BETWEEN'
			),
		),
);
global $post;
$wpdf_posts = get_posts( $wpdf_args );
foreach ( $wpdf_posts as $post ) :
	setup_postdata( $post );
	echo (get_the_title().'( '.get_permalink().' )<br/>');
endforeach; 
wp_reset_postdata();			

//	affichage de la boucle principale (non modifiée)
if ( have_posts() ) :
...

Voici l’affichage obtenu :

Seuls les articles d’identifiants « 2 » et « 4 » répondent aux conditions du paramétrage de la fonction get_posts() :

• ils appartiennent à la catégorie d’identifiant « 21 »
• ils ont des champs personnalisés nommés « ordre » et dont la valeur est comprise entre 10 et 100.

• global $post : il est préférable de déclarer l’utilisation de la variable globale $post,
• setup_postdata( $post ) : cette fonction met à jour la variable globale $post, ce qui permet d’utiliser les fonctions « dans la boucle »,
• wp_reset_postdata() : cette fonction remet la boucle principale dans l’état où elle était avant l’appel à la fonction setup_postdata( $post ),
• le paramètre meta_query utilise un tableau (array) de tableaux de conditions;  s’il n’y a qu’un seul tableau de conditions [ array( ‘key’ => ‘ordre’, ‘value’ => array( 10, 100 ), ‘type’ => ‘numeric’, ‘compare’ => ‘BETWEEN’ ], il est nécessaire de l’insérer dans un tableau. [array(array(..),)],

A noter :