5. ACF

Advanced Custom Fields (ACF) est une extension indispensable qui vous permet de définir des champs personnalisés pour tous vos contenus.

Le plugin va vous permettre par exemple de personnaliser le formulaire d'un film en y ajoutant des champs comme le nom du réalisateur, la date de sortie, la bande-annonce, etc.

Les avantages de la version pro

La version payante d'ACF a beaucoup d'avantages par rapport à la version gratuite et est souvent nécessaire pour des projets professionnels :

• Champ "répéteur" pour créer des groupes de champs répétables
• Champ "contenu flexible" pour créer des modules interchangeables
• Champ "galerie" pour créer des galeries d'images
• Champ "clone" pour dupliquer des champs
• Blocs personnalisés pour l'éditeur Gutenberg
• Pages d'options
• Synchronisation de la configuration dans des fichiers JSON

La tarification se présente sous forme d'abonnement annuel.

Installer ACF

ACF s'installe comme n'importe quel plugin. Sa version gratuite est disponible dans la bibliothèque d'extensions Wordpress.
Pour la version payante, il faudra l'acheter pour obtenir l'archive à importer.

Pour attribuer des champs à une page ou à un article, vous devez d'abord créer un groupe de champs.

L'emplacement d'un groupe de champs

Les groupes de champs doivent être attribués à un ou plusieurs emplacement(s).

La première liste de choix vous permet de sélectionner une typologie de contenu. Il peut s'agir d'une page, d'un article, d'une taxonomie, d'un type de contenu personnalisé (un film par exemple) ou même d'un widget, d'un utilisateur, etc.
La deuxième liste définit la condition entre "est égal à" ou "est différent de".
La troisième liste sera mise à jour automatiquement en fonction de ce qui a été sélectionné dans la première et déterminera la condition d'affichage du groupe de champs.

Les réglages

La section de réglages vous permet de définir l'apparence et la position du groupe de champs dans la page.
Vous pouvez choisir d'afficher les champs du groupe à l'intérieur d'un bloc ou bien directement dans la page. La première option est souvent plus esthétique.

Vous pouvez également sélectionner les champs que vous souhaitez masquer lorsque le groupe de champs est actif.

Ajouter des champs

Vous pouvez ajouter autant de champs que vous le souhaitez dans un groupe. Pour chaque champ créé, vous définirez obligatoirement :

• Un titre : le nom du champ affiché dans le back-office
• Un nom : le slug utilisé dans le template
• Un type : le type de champ à choisir parmi les options disponibles

En fonction du type sélectionné, vous verrez souvent apparaitre des options supplémentaires.

Les types de champs sont listés dans la documentation d'ACF et sont divisés en cinq catégories :

• Champs basiques : textes et nombres
• Contenu : médias et textes enrichis
• Choix : listes de sélection
• Relationnel : relations avec d'autres contenus
• jQuery : sélecteurs de dates et de couleurs, Google Maps
• Disposition : mise en page du groupe de champs

Champs basiques

Il existe 7 champs dans la catégorie "basique" :

• Texte : texte court (une seule ligne)
• Zone de texte : texte long (plusieurs lignes)
• Nombre : caractères numériques uniquement
• Curseur numérique : chamb nombre avec curseur
• Email : saisie d'adresse email uniquement
• URL : saisie d'URL uniquement
• Mot de passe : saisie masquée

Pour afficher la valeur d'un champ dans un template, vous utiliserez la fonction the_field() en passant en paramètre le nom du champ.
Au même titre que les fonctions the_title() et the_content(), vous devrez utiliser cette fonction à l'intérieur de la boucle.

Si vous avez un champ de texte nommé director, vous afficherez donc son contenu en écrivant the_field('director').

Vous aurez souvent besoin de récupérer la valeur d'un champ sans l'afficher. Vous utiliserez alors la fonction get_field().
Cela est utile pour vérifier si un champ existe avant de l'afficher, ou pour les champs particuliers comme les fichiers qui ne peuvent être affichés directement.

Contenu

Image / Fichier

Lorsque vous créez un champ de type Image ou Fichier, vous devez choisir entre trois options pour la valeur affichée dans le template :

• Données du fichier : retourne un array contenant toutes les informations sur le fichier
• URL : retourne l'URL du fichier
• ID : retourne l'identifiant du fichier

En sélectionnant la première option, vous ne pourrez utiliser the_field() puisque la valeur retournée sera un array.
Vous devrez donc récupérer cet array dans une variable à l'aide de get_field().

Pour afficher une image, vous avez trois options :

Option 1 :
Vous choisissez la valeur de retour "ID de l'image" et vous utilisez la fonction wp_get_attachment_image() pour générer la balise <img> correspondante.

Option 2 :
Vous choisissez la valeur de retour "URL de l'image" et vous la passez comme attribut src d'une balise <img>.

Option 3 :
Vous choisissez la valeur de retour "Données de l'image" et vous choisissez les paramètres à afficher.

Éditeur de contenu

Le champ "Éditeur de contenu" affiche un éditeur de texte enrichi. Deux paramètres sont disponibles :

• Onglets : choix du type d'éditeur entre éditeur visuel, texte brut (HTML) ou les deux
• Barre d'outils : complète (toutes les options sont activées) ou basique (uniquement certaines options)

Pour afficher la valeur de ce champ, vous utiliserez toujours la fonction the_field().

oEmbed

Un "oEmbed" est un contenu embarqué. Il s'agit le plus souvent d'une vidéo YouTube ou Vimeo, d'un post Facebook, Instagram ou Twitter ou d'un son SoundCloud.

La liste des services qu'il est possible d'embarquer avec ce champ est disponible ici.

Pour embarquer une vidéo YouTube, il suffit de copier l'URL de la vidéo dans le champ. L'affichage se fait ensuite comme d'habitude avec the_field().

Galerie

Le champ "Galerie" permet de sélectionner plusieurs images et de les classer dans l'ordre de votre choix. Les paramètres de retour sont les mêmes que pour les champs Fichier et Image.

Il n'est pas possible avec ce champ d'utiliser the_field() puisque la valeur de retour sera un array. Il faudra donc utiliser get_field() pour récupérer l'array dans une variable puis le parcourir à l'aide d'une boucle.

Choix

Les champs de choix sont des champs de sélection parmi des options prédéfinies.

• Liste déroulante : choix unique ou multiple dans une liste
• Case à cocher : choix multiple, valeur personnalisée possible
• Bouton radio : choix unique, valeur personnalisée possible
• Groupe de boutons : choix multiple
• Vrai / Faux : choix unique entre vrai ou faux

Pour tous ces champs à l'exception du champ "Vrai / Faux", vous devrez prédéfinir une liste d'options dans le paramètre "Choix". Vous y indiquerez un intitulé par ligne, précédé éventuellement par la valeur correspondante.

Vous choisirez ensuite la valeur à retourner dans le template entre la valeur de l'option, son intitulé ou les deux dans un array.

S'il s'agit d'un champ à choix multiples, la fonction the_field() affichera toutes les valeurs sélectionnées (ou leurs intitulés) séparées par des virgules. La fonction get_field(), en revanche, retournera un array.

Relationnel

Lien

Le champ "Lien" vous permet de créer un lien vers n'importe lequel de vos contenus (articles, pages, films ou autre contenu personnalisé) ou bien vers une page externe.

Vous pouvez indiquer une valeur personnalisée pour le texte du lien et choisir si vous souhaitez que le lien s'ouvre dans un nouvel onglet. Toutefois ces deux options ne seront pas prises en compte si vous sélectionnez l'URL comme valeur affichée dans le template.

En sélectionnant l'option "Données du lien (tableau)" comme valeur de retour, vous devrez utiliser get_field() qui retournera un array avec les paramètres suivants :

• title : Texte du lien
• url : URL du lien
• target : Cible du lien (_blank ou vide)

Lien vers page ou article

Le champ "Lien vers page ou article" permet de sélectionner un ou plusieurs contenus pour afficher leurs URLs. Contrairement au champ "Lien", il ne permet ni d'écrire une URL personnalisée ni de choisir un texte.

Pour afficher la valeur du champ dans votre template, vous utiliserez simplement the_field(). Si vous avez sélectionné plusieurs valeurs, une boucle sera nécessaire pour afficher chacune d'entre elles.

Objet Publication

Le champ "Objet Publication" permet de créer une relation avec un autre contenu de n'importe quel type. Les paramètres du champs permettent de restreindre la relation à un ou plusieurs type(s) de contenu(s) et à une ou plusieurs taxonomie(s).

Contrairement aux champs "Lien" et "Lien vers page ou article", celui-ci ne retournera pas simplement l'URL du contenu sélectionné mais l'objet lui-même, ou bien son ID en fonction de la valeur de retour choisie.

Pour afficher un contenu lié dans votre template, il faudra effectuer trois opérations :

1. Récupérer l'objet dans une variable $post via la fonction get_field()
2. Initialiser le contenu lié avec setup_postdata($post)
3. Restaurer le post de départ avec la fonction wp_reset_postdata()

Explications

Pour pouvoir utiliser les fonctions the_title(), the_content(), etc. sur le contenu lié, vous devrez modifier le contenu de la variable globale $post qui représente le post actuel (étape 1).

Vous indiquerez ensuite à Wordpress le nouveau contenu de la variable $post en utilisant la fonction setup_postdata()(étape 2). Cette fonction permet à Wordpress de redéfinir d'autres variables globales liées à $post en fonction du nouveau contenu.

À partir de cette deuxième étape, the_title() retournera le titre du contenu lié à la place de celui du contenu principal.

Lorsque vous avez terminé d'écrire le code du contenu lié, vous devrez restaurer le contenu initial en faisant un simple appel à la fonction wp_reset_postdata() (étape 3). La fonction the_title() retournera alors de nouveau le titre du contenu principal.

Exemple

Relation

Le champ "Relation" est une version avancée du champ "Objet Publication" qui permet de sélectionner plusieurs contenus liés et dispose d'options supplémentaires :

• Possibilité de filtrer par type de contenu et par taxonomie dans l'interface
• Activer ou désactiver le champ de recherche
• Afficher les images mises en avant dans les résultats
• Fixer un minimum et un maximum de contenus sélectionnables

Pour afficher tous les contenus liés, vous devrez utiliser une boucle et les fonctions setup_postadata() et wp_reset_postdata() vues précédemment.

Taxonomie

Le champ "Taxonomie" permet de sélectionner un ou plusieurs terme(s) d'une taxonomie. Trois options sont disponibles concernant la gestion des termes :

• Créer des termes : possibilité de créer de nouveaux termes directement depuis le champ
• Enregistrer les termes : si cette option est activée, les termes affectés via le champ seront également liés au contenu
• Charger les termes : si cette option est activée, les termes déjà liés au contenu seront présélectionnés dans le champ

jQuery

Les champs de la catégorie jQuery sont, à l'exception de Google Map, des champs basiques qui ne nécessitent pas de traitements particuliers.

Pour afficher une carte interactive à l'aide du champ Google Map, il sera nécessaire d'obtenir une clé d'API Google Maps et d'intégrer un code Javascript. La procédure et le code source Javascript sont disponibles sur la documentation officielle d'ACF.

Disposition

Message, accordéon et onglet

Le champ "Message" n'est pas un champ à proprement parler puisqu'il ne fait qu'afficher du texte dans votre formulaire.

Les champs "Accordéon" et "Onglet" permettent quant à eux d'organiser votre formulaire en créant des sections. De la même façon qu'un message, ces champs ne seront pas accessibles au niveau du template.
Les deux champs fonctionnent de la même façon : tous les champs placés après un accordéon ou un onglet seront affichés à l'intérieur.

Groupe

Le champ "Groupe" permet de grouper des champs au sein d'un même bloc. Vous pouvez y ajouter autant de sous-champs que vous voulez, et de n'importe quel type.

Contrairement aux onglets et aux accordéons, la disposition de champs dans un groupe aura un impact sur la façon dont vous récupérerez les données dans le template.

Pour récupérer les sous-champs d'un groupe, vous devrez d'abord effectuer une boucle sur le champ parent à l'aide de la fonction ACF have_rows(). Sur le même principe que la boucle classique de Wordpress, ACF embarque une fonction the_row() à appeler à chaque itération pour initialiser les sous-champs.

À l'intérieur de la boucle, il sera alors possible de lire chaque sous-champ à l'aide des fonctions the_sub_field() et get_sub_field().

Répéteur

Le champ "Répéteur" permet de définir un groupe de sous-champs répétable. Il fonctionne de la même façon que le champ "Groupe" avec des options supplémentaires pour gérer les nombres minimum et maximum d'éléments, le champ à afficher lorsqu'une ligne est repliée et l'intitulé du bouton d'ajout de nouvelle ligne.

L'affichage des contenus du répéteur dans un template se fait exactement comme pour un groupe, en utilisant la boucle have_rows() et the_row().

Contenu flexible

Les contenus flexibles permettent de créer plusieurs groupes de champs différents que l'utilisateur pourra organiser librement. Ce champ est très pratique pour réaliser des mises en page avec des contenus modulables.

Pour chaque groupe de champ du contenu flexible, vous devrez créer une nouvelle disposition et lui donner un intitulé et un nom.

Dans le template, les contenus flexibles fonctionnent comme les répéteurs et les groupes : on parcourt les dispositions avec la boucle have_rows() et on affiche les sous-champs avec the_sub_field().

À l'intérieur de la boucle, on utilisera la fonction get_row_layout(), qui retourne le nom de la disposition, afin de déterminer à chaque itération les sous-champs à afficher. On utilisera pour cela une simple condition :

Dans l'exemple ci-dessus, nous avons créé une disposition "Texte" contenant deux-sous champs "Titre" et "Texte" et une disposition "Galerie d'images" contenant un sous-champ "Images".
On effectuera donc une série de conditions sur la valeur de get_row_layout() : si la valeur est égale à text alors on affichera les sous-champs title et text. Si la valeur est égale à gallery, alors on affichera le champ images.

Pour chaque champ, vous avez la possibilité de cocher l'option "Logique conditionnelle" qui vous permettra de conditionner l'affichage du champ dans la formulaire à la valeur d'un ou plusieurs autre(s) champ(s).

Vous pouvez cumuler les règles soit avec des "et", soit avec des "ou".