have_rows WordPress : comprendre et maîtriser la boucle ACF

Introduction

Le fonctionnement de WordPress repose sur une multitude d'outils et de plugins qui permettent d'optimiser l'administration et la création de contenu. Parmi ces outils, le plugin Advanced Custom Fields (ACF) est particulièrement populaire pour sa flexibilité et ses fonctionnalités avancées. L'une des fonctions clés d'ACF est have_rows, qui joue un rôle central dans la gestion des champs répéteurs et des contenus flexibles.

Cet article explore en profondeur la fonction have_rows en environnement WordPress, en détaillant sa signature, son comportement, ses bonnes pratiques d'utilisation, les outils et ressources associées, ainsi qu'une FAQ pour répondre aux questions les plus fréquentes. L’objectif est de vous fournir un guide complet, orienté développeurs et intégrateurs, pour exploiter au maximum le potentiel d’ACF dans vos thèmes et projets WordPress.

Concepts clés autour de have_rows

Qu'est-ce que ACF ?

Advanced Custom Fields (ACF) est un plugin WordPress qui permet de créer des champs personnalisés de manière visuelle et structurée. Ces champs enrichissent l'interface d'administration et offrent une grande souplesse dans la gestion des contenus, bien au-del à des champs natifs titre / contenu / extrait.

ACF propose différents types de champs : texte, textarea, image, relation, répéteur (Repeater), contenu flexible (Flexible Content), galerie, groupe, etc. Les champs sont regroupés en groupes de champs (field groups) que l’on rattache à des types de contenus (articles, pages, CPT, taxonomies, utilisateurs, options, etc.).

Rôle exact de have_rows

have_rows est une fonction fournie par ACF qui permet de vérifier si un champ parent de type Repeater ou Flexible Content contient au moins une ligne de données à parcourir. Il ne s’agit pas d’une fonction de WordPress « cœur » mais bien d’une fonction spécifique au plugin ACF.

Concrètement, have_rows renvoie un booléen :

• true s’il existe au moins une ligne dans le champ répéteur ou flexible ciblé ;
• false sinon.

Cette fonction est pensée pourêtre utilisée conjointement avec the_row, sur le même modèle que la boucle WordPress classique have_posts / the_post. have_rows teste l’existence d’une ligne, tandis que the_row fait avancer le pointeur vers la ligne suivante et prépare le contexte pour les fonctions get_sub_field et the_sub_field.

Signature officielle de have_rows

La signature actuelle de la fonction est :

have_rows( string $selector, mixed $post_id = false ): bool

Les paramètres sont les suivants :

• $selector (string) : le nom du champ ou la clé du champ (par exemple 'mon_repeater' ou 'field_123abc').
• $post_id (mixed, optionnel) : l’identifiant du contexte dans lequel les données sont stockées. Par défaut, la valeur est false, ce qui signifie que la fonction utilise le post courant. Ce paramètre peut aussiêtre :
  • un ID de post ou de page (entier),
  • la chaîne 'option' pour les champs stockés dans la page d’options ACF,
  • un identifiant de terme de taxonomie, un ID d’utilisateur, ou d’autres contextes gérés par ACF selon la configuration des champs.

La fonction have_rows retourne toujours un booléen (true ou false) indiquant si au moins une ligne est disponible dans le champ parent ciblé.

Cette fonction aété introduite dans ACF à partir de la version 4.3.0 et fait désormais partie de l’API standard du plugin.

have_rows, the_row et portée (scope) de la boucle

Il est crucial de bien comprendre la différence de rôle entre have_rows et the_row :

• have_rows vérifie s’il reste des lignes à parcourir, mais ne modifie pas à lui seul la ligne courante.
• the_row fait avancer le pointeur vers la prochaine ligne et prépare le contexte pour les fonctions de sous-champs.

Cela signifie que :

• Utiliser have_rows dans une while sans appeler the_row à l’intérieur provoque une boucle infinie, car le pointeur ne progresse jamais.
• Les fonctions get_sub_field et the_sub_field ne ciblent que la ligne courante définie par the_row. Elles ne peuvent pas lire directement des données d’une autre ligne ni remonter automatiquement aux parents ou descendants.

Champs compatibles avec have_rows

La fonction have_rows est utilisée principalement avec :

• les champs répéteurs (Repeater), qui permettent de définir un groupe de sous-champs répétés autant de fois que nécessaire ;
• les champs de contenu flexible (Flexible Content), qui offrent des layouts multiples (blocs de contenu) pouvantêtre répétés et réordonnés.

Dans les deux cas, chaque itération de la boucle while ( have_rows ) correspond à une ligne ou un layout distinct, dont on peut récupérer les sous-champs avec get_sub_field ou the_sub_field.

Remplacement de l’ancienne fonction has_sub_field

Historiquement, ACF fournissait une fonction has_sub_field pour parcourir les sous-champs d’un répéteur. Cette fonction est désormais dépréciée au profit du couple have_rows + the_row. Si vous maintenez un vieux thème, il est recommandé de migrer progressivement votre code vers la nouvelle API pour profiter d’un comportement cohérent et compatible avec les versions récentes d’ACF.

Utilisation de base de have_rows en WordPress

Exemple simple avec un champ répéteur

Voici un exemple classique d’utilisation de have_rows avec un champ répéteur pour afficher une liste de témoignages :

 
 
Ils nous font confiance
 
  
 
 
  
 
  
 

Dans cet exemple :

• have_rows( 'temoignages' ) vérifie si le répéteur temoignages contient au moins une ligne.
• La boucle while parcourt chaque ligne.
• the_row prépare la ligne courante.
• the_sub_field affiche directement les sous-champs définis dans le répéteur ACF (par exemple texte, auteur, fonction).

Utilisation avec un champ Flexible Content

Pour un champ Flexible Content, la logique est similaire, mais on utilise souvent get_row_layout pour cibler le type de bloc affiché :

Cette approche est particulièrement pertinente pour construire des pages de contenuéditorial riche (landing pages, homepages, pages institutionnelles) tout en gardant un code de thème ordonné et maintenable.

Gestion du paramètre $post_id

Le second paramètre de have_rows, $post_id, permet de cibler un contexte différent du post courant :

• Pour un autre article ou une autre page :

  if ( have_rows( 'temoignages', 42 ) ) { // On parcourt les témoignages du post ID 42
  }
  

• Pour la page d’options ACF :

  if ( have_rows( 'reseaux_sociaux', 'option' ) ) { while ( have_rows( 'reseaux_sociaux', 'option' ) ) { the_row; // Sous-champs des réseaux sociaux }
  }
  

• Pour des champs rattachés à un utilisateur ou à une taxonomie, on passe l’identifiant approprié configuré dans ACF.

Le bon usage de $post_id est fondamental dès que vous centralisez des réglages ou des contenus globaux (options du thème, configuration d’en-tête/pied de page, blocs réutilisables, etc.).

Bonnes pratiques avec have_rows

Optimiser le contenu généré

Lorsque vous utilisez have_rows, il est recommandé d’adopter quelques réflexes pour garantir un rendu propre et optimisé :

• Vérifiez toujours que des données existent avant d’afficher du HTML structurant (titres, listes, sections) afin d’éviter les blocs vides.
• Prévoyez unétat « fallback » lorsque cela a du sens (par exemple, un message indiquant qu’aucunélément n’est disponible, ou une mise en page alternative).
• Appliquez des classes CSS spécifiques à chaque type de bloc répété ou layout flexible pour différencier l’apparence et faciliter la maintenance.
• Soignez la structure sémantique (titres hiérarchisés

  ,

  , listes, figures, sections) pour améliorer l’accessibilité et le référencement naturel.

Améliorer la structure du code

Une bonne structure de code est essentielle pour maintenir un projet WordPress professionnel etévolutif. Avec have_rows, quelques pratiques sont particulièrement utiles :

• Décomposez vos templates en fichiers partiels (par exemple get_template_part) plutôt que de concentrer toute la logique dans un seul gros fichier.
• Nommez vos champs ACF, groupes de champs, fonctions et partiels de manière claire et cohérente (préfixes de projet, noms explicites).
• Ajoutez des commentaires concis pour décrire les boucles principales, surtout lorsqu’elles sont imbriquées (répéteur dans un autre répéteur, ou répéteur dans un flexible content).
• Évitez la duplication de code : lorsqu’un même layout flexible est utilisé dans plusieurs templates, centralisez son rendu dans un fichier incluable (par exemple template-parts/flexible/bloc-texte.php).

Créer du contenu de qualité avec ACF et have_rows

have_rows n’est pas seulement un outil technique, c’est aussi un levier pour produire un contenu de haute qualité en WordPress :

• Assurez-vous que chaque entrée ajoutée dans un répéteur ou un flexible correspond à un besoinéditorial réel et apporte une valeur à l’utilisateur.
• Évitez de multiplier les champs répéteurs sans logique fonctionnelle : plus un back-office est complexe, plus il devient difficile à maintenir pour leséquipeséditoriales.
• Intégrez des médias pertinents (images, vidéos, icônes) via les sous-champs d’ACF, mais optimisez le poids des fichiers et utilisez les tailles d’image adaptées.
• Prévoyez des variantes de blocs (layouts flexibles) pour répondre à des scénarioséditoriaux différents, plutôt que de forcer un seul type de section à tout faire.

Performance et implications techniques

Sur des sites volumineux, l’utilisation intensive de champs répéteurs et de contenus flexibles peut avoir un impact sur les performances si elle n’est pas maîtrisée. Quelques points d’attention :

• Chaque appel à have_rows et the_row implique la lecture et la préparation des données du champ concerné. Sur de très gros répéteurs (centaines de lignes), le temps de génération de la page peut augmenter.
• Évitez les boucles profondément imbriquées lorsque cela n’est pas indispensable (par exemple, répéteur dans répéteur dans flexible). Si la structure devient trop complexe, envisagez de revoir le modèle de données.
• Lorsque vous avez besoin d’afficher uniquement un sous-ensemble d’informations, il peutêtre pertinent de filtrer ou de découper votre contenu plutôt que de tout charger systématiquement.
• Pensez au cache (objet cache, cache de page, transients) pour les sections lourdes et rarement modifiées, surtout si elles dépendent d’un répéteur d’options ou d’un flexible utilisé sur toutes les pages.

Cas pratiques avancés avec have_rows

Utilisation avec la page d’options ACF

La page d’options est très souvent utilisée pour gérer deséléments globaux : coordonnées, réseaux sociaux, éléments de pied de page, bannières, etc. Avec have_rows, l’accès est très simple :

Cette approche centralise les données et les rend faciles à mettre à jour par l’équipeéditoriale sans toucher au code.

Boucles imbriquées (nested loops)

Les répéteurs imbriqués sont fréquents dans les sites complexes (par exemple, des lieux contenant des membres, des sections contenant des sous-éléments, etc.). have_rows peutêtre utilisé de façon récursive :

Dans ce type de structure, veillez à bien ouvrir et fermer chaque boucle if / while pour conserver un code lisible et limiter les erreurs.

Utilisation de la clé de champ (field key)

Dans certains cas, il peutêtre préférable de cibler un champ par sa clé de champ (par exemple 'field_64ab12c3d4567') plutôt que par son nom. C’est notamment utile :

• lorsque le nom du champ est susceptible de changer,
• lorsque vous dupliquez des groupes de champs ou migrez entre environnements.

have_rows accepte indifféremment le nom ou la clé comme premier paramètre :

if ( have_rows( 'field_64ab12c3d4567' ) ) { while ( have_rows( 'field_64ab12c3d4567' ) ) { the_row; // Traitement des sous-champs }
}

Outils et ressources utiles autour de have_rows

Google Search Console

Bien que Google Search Console ne soit pas directement lié à ACF ou à have_rows, il joue un rôle important pour vérifier que vos gabarits de pages enrichis avec des champs personnalisés sont correctement explorés et indexés par les moteurs de recherche.

• Vérifiez que les pages utilisant des répéteurs ou des contenus flexibles ne génèrent pas d’erreurs d’exploration (liens cassés, redirections incorrectes, etc.).
• Surveillez les performances de vos pages clés (temps de chargement, Core Web Vitals) lorsque vous affichez de nombreuxéléments ACF.
• Exploitez les rapports de couverture et d’amélioration pour identifier d’éventuels problèmes de balisage HTML causés par un mauvais usage des boucles.

Outils de développement WordPress

Pour travailler efficacement avec have_rows et ACF, quelques outils sont particulièrement utiles :

• Mode debug de WordPress (WP_DEBUG) pour repérer rapidement les erreurs de syntaxe dans vos boucles et les problèmes de champs manquants.
• Plugins d’inspection ACF (ou simples fonctions de debug) pour afficher la structure et les valeurs des champs directement dans l’admin ou dans le front.
• Log PHP pour tracer les comportements inattendus lorsqu’un répéteur ne renvoie aucune ligne alors que vous vous y attendez.

FAQ sur have_rows et ACF

have_rows est-il une fonction native de WordPress ?

Non. have_rows est une fonction fournie par le plugin Advanced Custom Fields (ACF). Sans ACF actif (et sans les champs correspondants configurés), la fonction n’existe pas et provoquera une erreur fatale si elle est appelée.

Quels types de champs ACF sont compatibles avec have_rows ?

have_rows s’utilise avec les champs qui stockent des lignes multiples de données :

• le champ Repeater,
• le champ Flexible Content.

Il n’est pas destiné aux champs simples (texte, image, relation, etc.) qui ne gèrent pas de groupe de sous-champs répétés.

La fonction have_rows avance-t-elle automatiquement la ligne courante ?

Non. have_rows ne fait que tester l’existence d’une ligne disponible. C’est la fonction the_row qui incrémente le pointeur interne vers la ligne suivante. C’est pour cette raison qu’il est indispensable d’appeler the_row à l’intérieur de la boucle while ( have_rows ).

Que se passe-t-il si j’oublie d’appeler the_row dans ma boucle ?

Si vousécrivez :

while ( have_rows( 'mon_repeater' ) ) { // Pas de the_row ici
}

vous créez une boucle infinie. Le pointeur n’avance jamais, mais have_rows continuera à renvoyer true pour la première ligne disponible. Résultat : page blanche, temps d’exécution dépassé ou erreur serveur. Il est donc impératif de toujours appeler the_row dans la boucle.

Quelle est la différence entre get_sub_field et the_sub_field dans une boucle have_rows ?

À l’intérieur d’une boucle have_rows / the_row :

• get_sub_field( 'nom_du_champ' ) retourne la valeur du sous-champ, que vous pouvez stocker dans une variable, manipuler ouéchapper.
• the_sub_field( 'nom_du_champ' ) affiche directement la valeur, comme the_title ou the_content le font pour les contenus natifs.

Le choix dépend de votre besoin : obtenir la valeur pour un traitement plus complexe ou l’afficher telle quelle.

Puis-je utiliser have_rows en dehors de The Loop WordPress ?

Oui. have_rows ne dépend pas de la boucle principale de WordPress, tant que vous lui fournissez un $post_id correct si vous ne travaillez pas sur le post global courant. Par exemple pour afficher deséléments provenant d’une autre page ou de la page d’options, vous pouvez appeler :

if ( have_rows( 'elements_footer', 'option' ) ) { // Boucle sur leséléments de pied de page globaux
}

Comment migrer de has_sub_field vers have_rows ?

Si vous avez encore du code basé sur l’ancienne fonction has_sub_field, la migration se fait généralement en :

• remplaçant while( has_sub_field( 'mon_repeater' ) ) par while ( have_rows( 'mon_repeater' ) ) : the_row;,
• remplaçant les appels à get_sub_field / the_sub_field par les mêmes fonctions mais dans le nouveau contexte,
• vérifiant que les blocs if / else sont bien adaptés au comportement de have_rows.

Comment tester rapidement si un répéteur possède des lignes sans les afficher ?

Vous pouvez utiliser have_rows dans une simple condition, sans boucle, pour activer ou non une section :

if ( have_rows( 'faq' ) ) { // On sait qu'il existe au moins une entrée de FAQ
}

Pourêtre certain de ne pas perturber une autre boucle have_rows sur le même champ dans le même template, il est cependant conseillé de limiter ce type de vérification ou de s’organiser pour ne pas multiplier les tests sur le même champ.

Conclusion opérationnelle

La fonction have_rows est l’un des piliers de l’API d’Advanced Custom Fields pour WordPress lorsqu’il s’agit de gérer des contenus structurés complexes. En comprenant sa signature, son comportement exact, son association indispensable avec the_row, et en respectant les bonnes pratiques de structuration et de performance, vous pouvez construire des interfaces d’administration puissantes tout en conservant un thème propre, performant et maintenable.

Que ce soit pour gérer des listes de témoignages, des blocs de contenu flexibles, des options globales de site ou des structures hiérarchiques plus avancées, maîtriser have_rows vous permet de tirer pleinement parti d’ACF et d’élever significativement la qualité de vos projets WordPress.