Bouce personnalisée

Les boucles personnalisées

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…). 

Haut de page

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;
....
Boucle personnalisée - new WP_Query

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).
Modifier la boucle - utilisation d'une boucle personnalisée
Modifier la boucle – utilisation d’une boucle personnalisée

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),
Modifier la boucle - identifier les fonctions à utiliser "dans la boucle"
Modifier la boucle – identifier les fonctions à utiliser « dans la boucle »
  • 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.

Cet article présente des exemples d’utilisation de la classe WP_Query. Il est aussi possible de s’inspirer de ceux présentés dans l’article « modifier la boucle principale » car le choix des paramètres est identique.

Haut de page

Multi-paramétrage d’une requête

Enregistrer un article à l’état de brouillon :

Boucle personnalisée - enregistrer un brouillon d'article
Boucle personnalisée – enregistrer un brouillon d’article

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

Boucle personnalisée - sauvegarder un article planifié
Boucle personnalisée – sauvegarder un article planifié

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() ) :
...
Boucle personnalisée - multi paramétrage d'une requête

Voici l’affichage obtenu :

Boucle personnalisée - multi paramétrage d'une requête
Boucle personnalisée – multi paramétrage d’une requête

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’ ] :

Boucle personnalisée - modification des ordres de tri
Boucle personnalisée – modification des ordres de tri

Astuce
L’article A more powerful ORDER BY in WordPress 4.0 décrit l’amélioration apportée à l’instruction « orderby » à partir de la version 4.0 de WordPress.

Haut de page

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() ) :
...
Boucle personnalisée - sélection sur une période de temps

Voici l’affichage obtenu :

Boucle personnalisée - sélection sur une période de temps
Boucle personnalisée – sélection sur une période de temps

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…

Haut de page

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();
Boucle personnalisée - sélection sur les champs personnalisés

Voici l’affichage obtenu :

Boucle personnalisée - sélection sur les champs personnalisés
Boucle personnalisée – sélection sur les champs personnalisés

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 :

Boucle personnalisée - plusieurs champs personnalisés pour sélection
Boucle personnalisée – plusieurs champs personnalisés pour sélection
Haut de page

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 :

Boucle personnalisée - saisir des champs personnalisés
Boucle personnalisée – saisir des 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(
        '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() ) :
...
Boucle personnalisée - meta query avec clauses

Voici l’affichage obtenu :

Boucle personnalisée - multipes meta query
Boucle personnalisée – multipes meta query
  • 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).

Astuce
L’article Query improvements in WP 4.2: ‘orderby’ and ‘meta_query’  décrit l’utilisation des clauses dans les meta query à partir de la version 4.2 de WordPress.

Haut de page

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() ) :
Boucle personnalisée - get_posts()

Voici l’affichage obtenu :

Boucle personnalisée - get_posts()
Boucle personnalisée – get_posts()

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)

Haut de page

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 :

Boucle personnalisée - fonctions "dans la boucle" avec get_posts()
Boucle personnalisée – fonctions « dans la boucle » avec get_posts()

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 :

dans ce cas, la fonction « setup_postdata(  ) » doit être appliquée sur la variable globale $post et rien d’autre.

Haut de page

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Ce site utilise Akismet pour réduire les indésirables. En savoir plus sur comment les données de vos commentaires sont utilisées.