WPGraphQL expose par défaut l’ensemble des champs natifs de WordPress : titre, contenu, auteur, taxonomies. Mais la plupart des projets réels s’appuient largement sur Advanced Custom Fields (ACF) pour structurer du contenu métier : une page d’accueil avec des blocs personnalisés, une fiche produit avec des caractéristiques techniques, une page d’équipe avec des profils répétés.
Par défaut, ces champs ACF n’apparaissent pas dans le schéma GraphQL généré par WPGraphQL. C’est là qu’intervient l’extension complémentaire WPGraphQL for ACF, qui fait le pont entre les groupes de champs configurés dans l’interface ACF et le schéma GraphQL consommé par votre frontend.
Installation et prérequis
Trois plugins doivent cohabiter pour ce tutoriel : Advanced Custom Fields (dans sa version gratuite ou Pro selon vos besoins), WPGraphQL, et l’extension WPGraphQL for ACF, développée par la même équipe que WPGraphQL. Une fois les trois activés, chaque groupe de champs ACF existant dispose d’une nouvelle option dans son écran de configuration.
Exposer un groupe de champs
Dans l’écran d’édition d’un groupe de champs ACF, une nouvelle section « GraphQL » apparaît. Il suffit d’activer l’option Afficher dans GraphQL et de renseigner un Nom du type GraphQL pour ce groupe, par exemple ficheProduit. Ce nom détermine comment le groupe sera interrogeable dans vos requêtes.
Prenons un exemple concret : un groupe de champs « Caractéristiques produit », attaché au type de contenu produit, avec les champs prix, reference et un champ répéteur specifications composé de sous-champs libelle et valeur.
query FicheProduit($slug: ID!) {
produit(id: $slug, idType: SLUG) {
title
caracteristiquesProduit {
prix
reference
specifications {
libelle
valeur
}
}
}
}
Le cas des champs répéteur et flexible content
Les champs de type répéteur (Repeater) sont exposés comme des listes d’objets, chaque itération correspondant à un nœud avec ses propres sous-champs. C’est directement visible dans l’exemple précédent : specifications renvoie un tableau, chaque élément portant libelle et valeur.
Les champs de type contenu flexible (Flexible Content), souvent utilisés pour construire des pages modulaires avec plusieurs mises en page possibles, sont exposés comme des types d’union GraphQL. La requête doit alors préciser, pour chaque type de bloc possible, les champs attendus via la syntaxe ... on NomDuBloc :
query PageAccueil {
page(id: "accueil", idType: URI) {
blocsContenu {
blocs {
... on BlocsContenuBlocsTexteLayout {
titre
texte
}
... on BlocsContenuBlocsGalerieLayout {
images {
sourceUrl
}
}
}
}
}
}Cette syntaxe demande un peu de pratique au début, mais elle reflète fidèlement la logique de contenu modulaire d’ACF, bloc par bloc, sans perte d’information.
Cas pratique : une page d’accueil pour Next.js
Sur un projet récent, nous avons utilisé cette approche pour construire une page d’accueil entièrement pilotée par des blocs de contenu flexible ACF, consommés par un frontend Next.js. Chaque bloc (texte, galerie, mise en avant d’articles) correspond à un composant React distinct, sélectionné dynamiquement en fonction du type retourné par GraphQL :
- Un champ répéteur pour les logos partenaires affichés en bandeau
- Un champ contenu flexible pour la construction libre de la page par l’équipe marketing
- Un champ relationnel ACF, également exposé en GraphQL, pour mettre en avant des articles liés
Nommez vos groupes de champs GraphQL avec la même rigueur que vos composants frontend. Un nom de type GraphQL cohérent avec le nom du composant React qui le consomme rend le code beaucoup plus lisible six mois plus tard.
En résumé
WPGraphQL for ACF comble une lacune importante de WPGraphQL seul : sans cette extension, tout le contenu structuré construit avec ACF resterait invisible côté GraphQL. Avec elle, l’activation d’un groupe de champs se résume à une case à cocher et un nom de type, pour un résultat immédiatement exploitable côté frontend. C’est aujourd’hui un duo quasiment incontournable pour tout projet headless WordPress qui s’appuie sur ACF pour structurer son contenu.
