Référence complète pour l’ajout de groupes de champs personnalisés avancés et de champs par code
Le plugin Advanced Custom Fields (ACF) prend entièrement en charge la configuration des champs et des groupes par code PHP dans votre thème ou plugin. L’avantage de cela est que tous vos champs seront disponibles quelle que soit l’instance WordPress sur laquelle vous travaillez (par exemple, si vous devez basculer entre le serveur local, le serveur de test et le serveur en direct). Vous pouvez configurer tous les champs dans l’administrateur d’ACF et utiliser l’outil d’exportation pour l’exporter vers PHP.
Cependant, si vous le faites fréquemment, vous remarquerez peut-être que l’exportation PHP d’ACF contient beaucoup de code, ce qui rend vos fichiers PHP inutilement longs. Dans certains cas, il est préférable d’écrire le code vous-même, avec le strict minimum nécessaire, pour un code plus propre dans votre thème ou plugin. Ce guide vise à vous fournir une référence complète sur la façon d’écrire manuellement l’ajout de champs et de groupes ACF en PHP. Veuillez noter qu’il n’entrera pas dans les détails de chaque type de champ car il suppose que vous êtes déjà familiarisé avec les différents champs possibles dans ACF.
Mais d’abord; quelques précautions
Pour maintenir de bonnes normes de code et vous assurer que votre site WordPress ne plantera pas, vous devez toujours vérifier si les fonctions ou les classes que votre code utilise existent réellement. Surtout quand il s’agit de plugins qui peuvent être facilement désactivés ou même pas installés sur un site, vous devez toujours envelopper votre code spécifique au plugin dans un test if qui vérifie si les fonctions que vous utilisez existent, avant de les utiliser.
Quant à ACF, vous pouvez le faire en vérifiant si la classe 'acf'existe ou si la fonction d’ajout de champs et de groupes, 'acf_add_local_field_group', existe. Enveloppez l’un ou l’autre de ceux autour du code ci-dessous.
if (function_exists('acf_add_local_field_group')) {
// Your ACF specific code here
}
// OR:
if (class_exists('acf')) {
// Your ACF specific code here
}Code squelette
Pour ajouter des boîtes méta (groupes) et des champs, nous utilisons le crochet nommé acf/init. A l’intérieur de la fonction, nous appelons la fonction acf_add_local_field_group()avec un tableau comme paramètre. À l’intérieur de ce tableau se trouve la configuration complète du groupe et de tous ses champs. Les plus importantes sont les clés de tableau 'fields'et 'location'. Pour la clé de tableau, 'fields'vous fournissez le tableau pour tous les champs, et pour la clé 'location', vous fournissez les paramètres de l’endroit où la métabox doit apparaître. Cet article détaillera les options possibles que vous avez pour chacun de ces éléments ci-dessous.
C’est le strict minimum pour ajouter un groupe, mis à part les champs et l’emplacement :
Chaque groupe a besoin d’une clé unique, mais le nom lui-même n’a pas beaucoup d’importance (pour nous). Si vous ajoutez d’autres groupes, n’oubliez pas de modifier le 'key'champ. Le titre de la métabox peut être défini dans l’élément clé du tableau, vous l’avez deviné, 'title'. Si vous ajoutez plusieurs métaboxes au même emplacement (par exemple en post-édition), vous pouvez contrôler laquelle vient en premier en fournissant des numéros différents dans 'menu_order'.
Vous pouvez contrôler la conception de la métabox en fournissant soit defaulteller seamlessdans 'style'. Cependant, avec le nouvel éditeur Gutenberg, cela a beaucoup moins d’importance. Il en va de même pour la clé 'position'où, autrefois, vous pouviez positionner la métabox sous le contenu du message ('normal'), sur le côté ('side') ou juste après le titre du message ('acf_after_title').
Très bien! Plongeons-nous dans les deux éléments les plus intéressants du tableau ; en commençant par l’emplacement – qui définit où la métabox apparaît.
Emplacement
Tout dépend de ce que vous mettez dans la clé 'location'. Mais avant d’examiner les options possibles, nous devons comprendre sa structure de tableau.
'location'accepte un tableau avec un tableau d’éléments dans un tableau ! Tenir bon. Oui, car il est possible de fournir et de combiner la logique ET et OU à l’emplacement (par exemple "afficher dans la publication mais pas si le type de publication est ‘livre’", ou "afficher dans l’écran d’édition de l’utilisateur et également créer un nouvel écran utilisateur mais pour les deux cas pas si le rôle actuel est auteur"). La façon dont vous signifiez s’il s’agit d’un ET ou d’un OU consiste à structurer les tableaux. C’est beaucoup plus facile à montrer qu’à expliquer avec des mots :
Voici comment vous combinez deux éléments de localisation avec la logique ET (les deux doivent être vrais) :
Et c’est pour combiner des emplacements avec la logique OU (un seul doit être vrai):
Regarde la différence?
OK, passons à autre chose. Chaque option d’emplacement se compose d’un tableau de trois éléments ; 'param'c’est là que nous ajoutons tous les différents emplacements, 'operator', et 'value'. L’opérateur est de savoir comment comparer la valeur, et il peut être '=='égal ou '!='non égal à.
Passons en revue les options possibles une par une.
Localisation par type de poste
Définissez le type de publication souhaité dans 'value'. Gardez à l’esprit que vous ne pouvez pas fournir un tableau de plusieurs types de publication, vous devez combiner plusieurs de ces tableaux dans une configuration ET.
Localisation par statut de poste
Définissez le statut de publication souhaité sur 'value'. Encore une fois, gardez à l’esprit que vous ne pouvez pas fournir un tableau de plusieurs statuts de publication, vous devrez fournir chaque valeur souhaitée dans une configuration AND ou OR.
Emplacement par modèle de page
Cela ne s’affiche que si la page sélectionnée (ou le type de publication personnalisé avec prise en charge du modèle de page) a choisi le nom de modèle de page fourni.
Emplacement par terme de taxonomie attribué
Cet emplacement est utilisé lorsqu’un message est associé à un terme spécifique. Vous devrez fournir le nom de la taxonomie, deux-points et le slug du terme comme valeur.
Emplacement par type de page
ACF regroupe les propriétés spéciales des pages en «type de page ». Il s’agit principalement de savoir si la page actuelle est ou non une page parent ou enfant, mais aussi de cibler des pages définies comme page d’accueil WordPress ou page de blog.
Emplacement : taxonomie
Emplacement à utiliser lors de la modification ou de l’ajout d’un terme dans une taxonomie.
Indiquez le nom de la taxonomie sous la forme 'value'. Gardez à l’esprit que vous ne pouvez pas fournir un tableau de plusieurs taxonomies, mais vous pouvez fournir 'all'pour cibler toutes les taxonomies.
Emplacement : utilisateur
Cet emplacement permet d’ajouter ou de modifier un profil d’utilisateur.
Indiquez 'edit‘ pour cibler uniquement l’écran de modification des utilisateurs existants, 'register'pour cibler uniquement le formulaire lors de l’enregistrement d’un nouvel utilisateur, ou ‘ all'pour les deux éléments ci-dessus.
Depuis ACF 5.6, vous pouvez également ajouter des groupes de champs aux éléments de menu.
Vous pouvez configurer valuepour allappliquer le groupe à tous les éléments de menu, ou vous pouvez spécifier des menus soit par emplacement (emplacements enregistrés dans votre thème) soit par ID de menu. Pour l’utilisation de l’emplacement 'location/<name>'– ainsi, pour un emplacement nommé ‘ primary‘, vous pouvez définir la valeur sur 'location/primary'pour appliquer votre groupe à un menu attribué à cet emplacement uniquement. Si vous souhaitez cibler un ID de menu spécifique, définissez la valeur sur une chaîne de cet ID.
Emplacement: Widget
ACF vous fournit même un emplacement dans les paramètres du widget sans modifier le code du widget principal.
Vous pouvez cibler tous les widgets avec 'all'as 'value'ou cibler un widget spécifique. Vous aurez besoin de connaître «l’ID interne» du widget avec lequel ils sont enregistrés.
Emplacement : page Options ACF (Pro uniquement)
Avec ACF Pro, vous pouvez utiliser ACF pour configurer des pages d’administration personnalisées.
Indiquez le nom que vous avez défini acf_add_options_pagedans menu_slugas 'value'.
Emplacement : bloc (Pro 5.8+ uniquement)
ACF Pro (5.8+) a une fonctionnalité pour ajouter des blocs Gutenberg avec des champs d’ACF et contrôler sa sortie avec PHP. Assez astucieux pour ceux qui n’ont pas encore plongé dans l’ajout de blocs Gutenberg personnalisés et du Javascript requis.
Des champs
Nous entrons maintenant dans la partie la plus intéressante; les champs eux-mêmes. ACF propose une (vraiment) large gamme de types de champs, et je le répète ; ce guide ne vous montre pas ce qu’est chaque champ et comment ils fonctionnent ou ressemblent.
Dans le tableau de base que vous fournissez 'fields', acf_add_local_field_group()vous fournissez un tableau où chaque champ est son propre tableau.
Le minimum absolu requis pour chaque champ est le suivant : un unique 'key'qui peut être tout ce que vous voulez et vous n’aurez probablement jamais besoin de vous y référer. Vous avez également besoin 'name'de la clé méta (post, user, term) dans laquelle la valeur du champ est enregistrée – et c’est celle à laquelle vous vous référerez lors de l’obtention de la valeur des champs. Vous devez fournir un 'label'et enfin le crucial 'type'qui définit le type de champ que nous traitons. Le reste des champs dépend de, 'type'comme nous le verrons lorsque nous passerons en revue chaque type de champ ci-dessous.
Il s’agit du code squelette pour ajouter un champ.
Gardez à l’esprit que vous aurez besoin de ce qui précède pour chaque champ, mais pour ne pas répéter le même code, chaque type de champ ci-dessous n’inclura 'type'que tous les autres éléments nécessaires pour ce type de champ.
Champ: Saisie de texte
Le champ le plus simple de tous. Tout ce dont nous avons vraiment besoin est :
Mais pour personnaliser davantage votre saisie de texte, vous pouvez également fournir l’un des éléments suivants :
Champ: Saisie numérique
Champ : zone de texte
Champ : Curseur de plage
Champ : Mot de passe
Identique à la saisie de texte, sauf que tout ce que vous y tapez sera couvert de * comme vous vous en doutez dans un champ de mot de passe.
Champ : Image
Sélection d’une seule image.
Champ : Fichier
Similaire à l’image ci-dessus, sauf qu’elle ne prévisualise pas le fichier.
Vous pouvez également le fournir 'mime_types' => '',et le définir, par exemple, 'pdf,docx'pour autoriser uniquement les fichiers PDF et DOCX.
Champ : Éditeur WYSIWYG
WYSIWYG est un éditeur «What You See Is What You Get» – celui que nous connaissions avant l’arrivée de Gutenberg (TinyMCE).
Le paramètre 'media_upload'et 'delay'peut être 1 (vrai) ou 0 (faux).
Champ: Sélectionnez
Champ: Case à cocher
Notez qu’il 'default_value'peut s’agir d’un tableau de choix multiples.
Champ: bouton radio
Le réglage 'other_choice'sur true ajoute un bouton radio supplémentaire intitulé "Autre" avec une entrée de texte où l’utilisateur peut taper quelque chose.
Champ: vrai/faux (bascule)
Le 'ui_on_text'et 'ui_off_text'n’est valide que si 'ui'vaut 1, car ils définissent ce qui doit apparaître sur le basculeur spécial de l’interface utilisateur.
Champ: Lien
Vous donne un bouton pour entrer un lien, soit en tapant, soit en choisissant parmi le contenu de votre site WordPress (devrait être familier avec l’ajout d’un lien dans l’éditeur WordPress normal).
Champ : Publier un objet
Donne une boîte de sélection où vous pouvez choisir parmi le contenu WordPress. La sélection vous permet de rechercher en tapant et tout le contenu est divisé par type de publication. Vous pouvez autoriser la sélection de plusieurs publications ou d’une seule.
Champ : Relation
Champ : choisir des termes dans une taxonomie
Le sélecteur de termes de taxonomie a quatre "modes" ou types différents où deux d’entre eux permettent des choix multiples.
Champ : sélectionnez l’utilisateur
Champ: Google Maps
Gardez à l’esprit que vous devez fournir une clé d’API GoogleMaps valide à ACF pour que ce champ fonctionne, comme ceci :
add_filter('acf/fields/google_map/api', function($api) {
$api['key'] = 'YOURAPIKEY';
return $api;
});Champ : Sélecteur de date
Champ : Sélecteur de date et d’heure
Champ : Sélecteur de temps
Champ: Sélecteur de couleurs
Champ: Galerie (ACF Pro uniquement)
Types de champs spéciaux
ACF propose également certains types de champs qui n’enregistrent pas de valeur en soi, mais ils sont davantage destinés à des fins organisationnelles. Pour tous ceux-ci, définissez 'name'une chaîne vide.
Message HTML
Si vous avez simplement besoin d’imprimer du code HTML sans enregistrer de valeur, vous pouvez utiliser type 'message'.
Répéteur (ACF Pro uniquement)
Un répéteur contient un tableau de champs qui peuvent être répétés.
L’élément sub_fieldsattend un tableau de champs, tout comme vous avez configuré les champs ci-dessus.
Conclusion
Il ne s’agit en aucun cas d’un guide exhaustif, car ACF propose un large éventail d’options et de personnalisations. Mais il devrait couvrir les options les plus utilisées et les cas d’utilisation personnalisés. Personnellement, je me réfère assez souvent à cela chaque fois que j’ajoute des champs ACF pour les clients. Et même pour les options les plus étranges, ce guide est suffisant pour que je n’aie pas besoin de gonfler mes fichiers PHP avec le code d’exportation d’ACF. J’espère que cela vous a été utile aussi !