Formation « Des champs administrables avec ACF »

Export Json des groupes ACF : Synchronisation local – en ligne

Lecture : 5 minutes • 0

Il est possible d’exporter les groupes de champs automatiquement afin d’en garder une trace en JSON ce qui présente plusieurs avantages, comme pouvoir versionner nos champs et les synchroniser plus facilement en ligne.

Il existe plusieurs façons d’exporter ses champs ACF : manuellement ou automatiquement, en JSON ou en PHP. On va voir chacune des techniques et les avantages et inconvénients qu’elles représentent.

Exporter et importer les champs manuellement

La première méthode est d’exporter vos champs manuellement via l’outil d’import/export que vous trouverez dans le menu ACF > Outils.

L'interface d'import et d'export des groupes de champs ACF
Cette page vous permet d’importer et d’exporter vos groupes de champs

Sélectionnez vos champs et cliquez sur Exporter le fichier. Un fichier au format JSON sera téléchargé sur votre ordinateur.

Cela peut être très pratique si vous avez besoin de réutiliser un groupe de champs sur un autre site. Vous pourriez de cette manière vous composer une librairie de groupes de champs réutilisables pour être encore plus efficace sur vos futurs projets.

Dans ce cas, n’exportez qu’un groupe de champs à la fois, afin de générer un fichier distinct pour chacun d’entre eux.

Voici à quoi ressemble le JSON d’un groupe :

JSON

Le fichier, quoi que fourni, est assez simple à comprendre puisque l’on retrouve les données de notre groupe de manière assez lisible.

On voit un tableau fields qui contient nos champs, et chacun d’entre-eux possède ses propres données comme le type (text, relationship…), le nom ou encore les valeurs par défaut, la logique conditionnelle

Conseil

Exportez vos groupes de champs pour vous faire une librairie et les réutiliser dans vos prochains projets.

Exporter ses champs en JSON automatiquement

Export ACF vers JSON

Maintenant, on va voir comment exporter automatiquement vos groupes de champs en JSON.

Quels sont les avantages de l’export automatique en JSON ?

Dès lors que vous modifierez un groupe, un export JSON se fera automatiquement dans le dossier de votre thème. Cela permet de :

  • Versionner vos champs et leurs configurations avec Git ;
  • Synchroniser vos champs entre différentes instances de votre site (local et en ligne par exemple).

En agence, c’est très pratique : lorsqu’un collaborateur récupère votre projet et installe le site WordPress, il pourra synchroniser les champs d’un clic et travailler sur le site. Pas besoin de récupérer la base de données donc.

Et comme c’est versionné, vous gardez un historique de toutes vos modifications concernant les réglages des groupes, des champs et leurs réglages.

Le plus gros avantage, c’est de pouvoir travailler vos nouveaux champs en local, et les envoyer en ligne pour synchronisation une fois prêts.

Mon astuce, c’est de synchroniser les nouveaux champs avant de mettre en production ma nouvelle version : les données des anciens champs continueront de fonctionner, et les nouveaux seront prêts à l’emploi.

Les rédacteurs du site pourront alors commencer à saisir le contenu pour éviter une interruption au moment de la mise en production.

Conseil

N’attendez pas la mise en production pour synchroniser vos groupes de champs. Le faire en avance ne supprimera pas les anciennes données, et permettra de saisir le contenu en avance.

Configurer l’export automatique en JSON

Pour activer l’export automatique, c’est extrêmement simple puisqu’il vous suffit d’ajouter ce petit bout de code dans functions.php :

PHP
functions.php

Ce code se hook sur la fonction d’enregistrement des groupes de champs.

Désormais, lorsque vous modifierez les réglages d’un groupe, un fichier JSON sera créé (ou mis à jour) dans le dossier /acf-json/ de votre thème.

Aperçu du dossier acf-json qui stocke les fichiers d'exports de nos groupes de champs
Les groupes de champs apparaissent dans le dossier après modification

Ajoutez ce code dès le début d’un projet afin que les groupes apparaissent immédiatement après leur création !

Synchroniser un groupe de champs

Lorsqu’un fichier JSON possède des données plus récentes que le groupe de champs, alors ACF vous informe grâce à une icône « Synchronisation disponible ».

L'interface des groupes de champs indique quand une synchronisation est disponible
Une version plus récente de ce groupe de champs est disponible

Cela arrive lorsqu’un autre développeur de votre équipe a modifié les champs, puis a commit ses modifications via git, ou alors lorsque vous mettez en ligne les fichiers JSON de vos groupes de champs modifiés initialement en local.

Cliquez sur « Synchronisation disponible » en haut du tableau et lancez la ou les synchronisations.

Depuis ACF 5.9 (sorti en juillet 2020), une interface montre quelles sont les modifications qui seront apportées à vos groupes après synchronisation :

L'interface de comparaison des groupes de champs avant synchronisation
Comparez les différences avant de synchroniser

On y voit, en vert, les éléments ajoutés, et en rouge, ceux supprimés, exactement comme avec l’interface de révision des articles.

Exporter ses champs en PHP

Export ACF vers PHP

L’autre solution, c’est d’exporter les champs en PHP au lieu de JSON. Dans ce cas, leur structure ne sera plus enregistrée en base, mais directement dans le code de votre thème.

Quels sont les avantages et inconvénients de l’export PHP ?

Dans cette solution, vous allez également pouvoir versionner vos champs puisqu’ils sont désormais en PHP.

L’avantage c’est que, sur un site en ligne, vous et les autres administrateurs du site n’auront plus accès à leur configuration dans le menu de WordPress. De cette manière, on s’assure que personne ne fera de bêtises en modifiant le nom d’un champ en production, ce qui pourrait tout casser.

Information

Dans ce cas, les champs sont déclarés par du code PHP, exactement comme on déclare un type de publication personnalisé, ou CPT.

En local, vous avez toujours le groupe de champs modifiable depuis le menu ACF, mais ce n’est plus lui qui est pris en compte, c’est votre code PHP.

Donc à chaque modification des paramètres, il faudra réexporter le PHP et le remplacer. Ou alors si vous êtes un guedin, vous pouvez directement modifier les paramètres en PHP.

Le plus gros avantage de cette approche, c’est que vous allez pouvoir internationaliser les chaines de textes de vos champs. Donc si vous faites un site multilingue, c’est clairement la meilleure approche à avoir !

Conseil

Optez pour l’export PHP des champs si vous faites un site multilingue.

Comment exporter les champs en PHP ?

Pour exporter vos champs en PHP, il faut là aussi se rendre dans ACF > Outils, sélectionner vos groupes et cette fois cliquer sur Générer le PHP.

L'interface d'import / export d'ACF
Cliquez cette fois sur Générer le PHP

Une nouvelle fenêtre apparaît et affiche votre code. Copiez-le :

Le code PHP généré automatiquement par ACF
Sélectionnez le code PHP généré et copiez-le

Ensuite, collez ce code dans votre fichier functions.php :

PHP
functions.php

Comme le code prend vite de la place, je vous conseille de créer des sous-fichiers et faire des require_once en PHP, comme on l’a vu dans le cours sur le fichier functions.php.

PHP
functions.php

Sinon, vous allez vite vous retrouver avec plusieurs centaines de lignes de configuration ACF.

Internationaliser les champs ACF

Maintenant, pour internationaliser les chaînes, c’est très simple, on va utiliser la fonction WordPress __() sur les libellés de nos champs.

PHP
functions.php

On va le faire notamment sur :

  • Les titres des champs : label ;
  • Leurs instructions : instructions ;
  • La description du groupe de champs ;

À éviter

Ne traduisez pas par contre les slugs des champs (name), sinon vos données n’apparaîtront plus dans les templates.

Réimporter des champs ACF précédemment exportés en PHP

Par contre, si vous supprimez votre site local, vos champs ne seront plus modifiables (ou alors seulement en PHP) et c’est la principale contrainte que je trouve à cette solution.

Mais heureusement, si cela venait à vous arriver, il existe une technique pour transformer le code PHP en JSON, afin de pouvoir réimporter vos champs dans WordPress :

PHP
functions.php

Une fois le code exécuté, vous pouvez le commenter car il ne sera plus utile. Je parle de cette solution plus en détails dans un article dédié sur le blog, si vous désirez en savoi plus.

Attention

Conservez toujours une version standard de vos groupes de champs, en local par exemple, afin de pouvoir conserver la possibilité de les modifier.


Vous connaissez maintenant toutes les techniques pour exporter vos champs. Alors laquelle choisir ?

Eh bien si vous devez gérer des sites multilingue, l’export PHP sera le plus judicieux car il vous permettra d’internationaliser les intitulés, mais si ce n’est pas le cas, l’export JSON se révélera être le plus efficace.

0

Questions, réponses et commentaires

Laisser un commentaire