() translation by (you can also view the original English article)
Bienvenue dans cette troisième partie de la série "Maitriser WP_Query". Dans le chapitre précédent, nous avons passé en revue les 13 fonctions différentes, liées à la classe WP_Query. Dans cette partie, nous allons voir les "hooks" de WordPress (des Filtres et des Actions) que vous pouvez utiliser avec WP_Query.
Allons y sans attendre !
Les Filtres liés à WP_Query
Dans le Codex, dans le chapitre consacré au filtres, il y a 16 filtres listés sous la dénomination "Filtres WP_Query". Dans ce chapitre nous allons les passer en revue. Ce chapitre sera assez cours car la plupart des filtres sont fonction de certaines clauses particulières de la requête faite par la classe WP_Query.
Nous y reviendrons, après avoir vu les filtres qui ne sont pas en lien avec ces "clauses" particulières.
Filtrer le nombre de post : found_posts
Ce filtre permet de spécifier un nombre de post renvoyé, sans prendre en compte l'argument post_per_page spécifié dans WP_Query.
Ce filtre est particulièrement utile pour créer des paginations. Voyons ce qu'en dit le Codex :
Par exemple, si vous déclaré une valeur de décalage dans votre requête, WordPress ne va PAS déduire le décalage grâce au paramètre $wp_query->found_posts parameter (si vous avez 45 posts affichable après un décalage de 10, WordPress va ignorer ce décalage et vous donner une valeur found_posts de 55).
Logique.
Filtrer la requête : found_posts_query
Le nombre d'éléments trouvés est calculé par la commande MySQL SELECT FOUND_ROWS() Ce filtre permet de modifier cette commande, au cas où vous auriez besoin de calculer le nombre d'éléments trouvés de manière différente.
Filtrer la requête SQL : post_request
Si vous désirez modifier la requête SQL, voici le filtre à utiliser. Ce filtre peut réécrire complètement la requête SQL faite par la classe WP_Query.
Filtrer les éléments retournés par la requête : posts_results
Si vous désirez modifier le tableau PHP généré par WP_Query, vous pouvez utiliser ce filtre. Voici un exemple très clair sur le Codex.
(Attention, notez bien que ce filtre prend en charge les données brutes générées par la requête SQL).
Filtrer le tableau des posts : the_posts
A la différence de posts_results, le filtre the_posts attend que la requête soit totalement retournée. Ainsi on peut vérifier dans le tableau si les posts sont publiés ou épinglés. Utilisez le si vous ne voulez pas de posts non-publiés dans vos résultats.
Filtrer la Field List (et la clause particulière SELECT ) : posts_fields
La clause SELECT d'une requête SQL détermine quel champs de la base de données sera sélectionné et ce filtre permet de les trier.
Filtrer la clause LIMIT : post_limits
La clause LIMIT d'une requête SQL définit les limites de la requête, et ce filtre permet de la trier.
La Clause DISTINCT de la requête de filtrage : posts_distinct
La clause DISTINCT d'une requête SQL indique que la requête doit retourner des résultats différents, et ce filtre permet de les trier. Naturellement, WP_Query ne retourne pas de résultats distincts mais lorsque vous utilisez ce filtre avec une fonction qui renvoie « DISTINCT », la requête sera ajustée pour retourner des résultats différents.
La Clause WHERE de la requête de filtrage : posts_where
La clause WHERE d'une requête SQL est utilisée pour filtrer les instructions MySqL : SELECT, INSERT, UPDATE ou DELETE, et ce filtre permet de les trier. Bien que la classe WP_Query fasse tout le travail nécessaire pour filtrer les résultats, vous pouvez aller plus loin en utilisant ce filtre.
Filtrer la Clause WHERE de la requête après le calcul de pagination : posts_where_paged
Ce filtre est un dérivé du filtre posts_where, que vous pouvez utiliser avec les requêtes de pagination.
Filtrage de la Clause WHERE d'une requête de recherche : posts_search
Ce filtre est un autre dérivé du filtre posts_where . Il permet de modifier la clause WHERE d'une requête utilisée pour obtenir des résultats de recherche..
Filtrage de la Clause JOIN : posts_join
La clause JOIN d'une requête SQL vous permet de travailler votre commande SQL au sein de plusieurs tables de base de données. C'est l'un des éléments avancés de MySQL, donc je ne recommande pas l'utilisation de ce filtre à moins que vous ne sachiez très bien comment fonctionne JOIN.
Filtrer la clause JOIN après que la page soit calculée : posts_join_paged
Tout comme posts_where_paged est une itération de posts_where, ceci est une itération du filtre posts_join qui travaille sur les requêtes de pagination.
Filtrer la clause ORDER BY : posts_orderby
La clause ORDER BY d'une requête SQL réorganise l'ordre de la requête, et ce filtre permet de filtrer l'ordre.
Filtrage de la Clause GROUP BY de la requête : posts_groupby
La clause GROUP BY d'une requête SQL retourne des éléments « groupés » par champ de base de données et ce filtre permet de trier en fonction des groupes.
Filtrer toutes les clauses de la requête : posts_clauses
Si vous voulez filtrer toutes les clauses dans le même temps, il y a aussi un filtre pour ça : posts_clauses. Ce filtre gère les clauses WHERE, GROUP BY, JOIN, ORDER BY,DISTINCT, SELECT, et LIMITS .
Les Actions liées à WP_Query
Maintenant que nous avons passé en revue les filtres associés à WP_Query, passons à l'autre type de hook : les actions.
Interférer avec la requête avant son exécution : pre_get_posts
Avant que la requête ne soit lancée, vous pouvez interagir avec elle (par exemple injecter des variables supplémentaire) à l'aide de cette action. Voyons un petit exemple de Tom McFarlin pour apprendre à exclure une catégorie de la boucle principale :
1 |
<?php
|
2 |
|
3 |
function tutsplus_exclude_category( $wp_query ) { |
4 |
|
5 |
/*
|
6 |
* Add the category to an array of excluded categories. In this case, though,
|
7 |
* it's really just one.
|
8 |
*/
|
9 |
$excluded = array( '-1' ); |
10 |
|
11 |
/*
|
12 |
* Note that this is a different, perhaps, cleaner way to write:
|
13 |
*
|
14 |
* $wp_query->set( 'category__not_in', $excluded );
|
15 |
*/
|
16 |
set_query_var( 'category__not_in', $excluded ); |
17 |
|
18 |
}
|
19 |
|
20 |
add_action( 'pre_get_posts', 'tutsplus_exclude_category' ); |
21 |
|
22 |
?>
|
Gérer l'analyse de la requête : parse_query
Contrairement à pre_get_posts, qui intervient avec la requête avant que les variables de la requête ne soient définies, l'action parse_query gère le processus une fois définies les variables de requête. Par conséquent, vous devez utiliser cette action si vous voulez vérifier les variables actuelles et agir conformément à celles-ci.
Modifiez le Post Object : the_post
Le terme the_action est un peu déroutant car c'est le nom d'un hook d'action, une fonction liée à WP_Query et également une méthode de la classe WP_Query.
Cette action, comme le dit le Codex, nous permet de modifier l'objet du message immédiatement après être retourné et réglé. À l'aide de cette action, vous pouvez modifier directement ce qui est retourné. Voyons un exemple :
1 |
<?php
|
2 |
|
3 |
function tutsplus_featured_badge( $post ) { |
4 |
|
5 |
if ( is_single() && in_category( 'featured' ) ) { |
6 |
|
7 |
echo '<div class="featured-badge">' . __( 'FEATURED', 'tutsplus' ) . '</div>'; |
8 |
|
9 |
}
|
10 |
|
11 |
}
|
12 |
|
13 |
add_action( 'the_post', 'tutsplus_featured_badge' ); |
14 |
|
15 |
?>
|
Fin de la troisième partie.
Les Actions et les filtres sont toujours un sujet intéressant à aborder. (Je sais pertinemment que mes deux séries sur les actions de WordPress et les Filtres WordPress ont ont été un plaisir à écrire et on reçu un bon accueil des lecteurs). J'espère que vous avez appréciez ce chapitre autant que j'ai pris de plaisir à l'écrire.
Envie d'ajouter des choses à cet article ? Laissez un commentaire ... Et, si vous avez apprécié cet article, n'hésitez pas à le partager !
Rendez-vous au prochain chapitre dans lequel nous parlerons des propriétés et méthodes de la classe WP_Query.
