# WPGraphQL for ACF : exposer vos champs personnalisés en GraphQL

> Tutoriel pour exposer vos champs Advanced Custom Fields dans le schéma WPGraphQL et les consommer facilement depuis un frontend headless.

- Auteur : Clément Hadrot
- Publié le : 2021-09-21
- Mis à jour le : 2021-09-21
- Catégorie : Headless & API
- URL : https://wpmoderne.dev.wordpress-developpement.fr/headless/wpgraphql-for-acf-champs-personnalises-graphql/

## L’essentiel

- L'option « Afficher dans GraphQL » suffit pour exposer un groupe de champs
- Le nom GraphQL du groupe détermine le nom du champ dans les requêtes
- Les champs répéteur ACF s'interrogent comme des listes imbriquées

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
      }
    }
  }
}
```

> L'essentiel à retenir : L'option « Afficher dans GraphQL » suffit pour exposer un groupe de champs ; Le nom GraphQL du groupe détermine le nom du champ dans les requêtes ; Les champs répéteur ACF s'interrogent comme des listes imbriquées

## 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.