Comment créer un formulaire frontal avec ACF

Dans ce didacticiel, je vais vous montrer comment créer un formulaire frontal avec les champs personnalisés avancés (ACF). Je vais détailler son fonctionnement et comment vous pouvez l’adapter à vos besoins.

Advanced Custom Fields (ACF) est un plugin gratuit qui vous aide à ajouter des paramètres de champ de tout un tas de types à presque tous les types de contenu dans WordPress. Vous pouvez ajouter des champs aux publications, aux taxonomies, aux menus, aux widgets, aux utilisateurs et même aux pages d’administration personnalisées. Son utilisation principale est pour l’administrateur, mais vous pouvez également l’utiliser pour générer les champs en front-end.

Les applications pour ajouter des champs ACF au front-end sont nombreuses ; vous pouvez ajouter un formulaire pour créer et mettre à jour des publications, des catégories ou des utilisateurs. Avec du code, vous pouvez même créer un formulaire de contact général où les réponses sont enregistrées en tant que messages de type de publication personnalisés et le code déclenche des notifications par e-mail sur les réponses au formulaire. Tout comme un formulaire de contact normal. L’utilisation de la fonctionnalité de formulaire frontal ACF pour créer des formulaires et permettre aux visiteurs de créer ou de modifier le contenu du site sans se connecter sont les utilisations courantes. Mais utilisez-le avec prudence. Cela s’ouvre facilement au spam et aux abus, et dans le pire des cas, les visiteurs peuvent détruire le contenu ou les paramètres de votre site. Vous devriez au moins exiger que les visiteurs se connectent avec des utilisateurs valides afin d’accéder aux formulaires qui peuvent modifier le contenu critique de WordPress (profil utilisateur, publications, etc.).

Ce que nous ferons

Je suppose que le site WordPress a défini un ensemble de champs supplémentaires sur les utilisateurs d’un rôle personnalisé (‘ member‘) à l’aide d’ACF. Ces utilisateurs n’ont pas du tout d’accès administrateur, mais nous voulons leur offrir la possibilité de modifier leurs champs personnalisés sur leur profil. La solution que j’ai choisie consiste à créer un modèle de page personnalisé pour mettre à jour leur profil, en n’affichant le formulaire que s’ils sont connectés et ont le bon rôle.

Je vais le garder assez simple dans ce tutoriel donc je n’inclurai pas d’exemple d’ajout des champs de profil utilisateur standard dans WordPress (email, mot de passe, etc.). Cela sort un peu du cadre de ce tutoriel. J’autoriserai uniquement la modification des champs ACF sur cette page de profil de modification.

Avec ACF, j’ai créé un groupe de champs avec un ensemble de paramètres pour les utilisateurs membres :

Et j’ai un modèle de page personnalisé dans mon thème qui ressemble actuellement à ceci – pour le moment, il ne s’agit que d’un modèle de page simple et standard ;

À la ligne, #11nous vérifions si l’utilisateur actuel est connecté et a le rôle personnalisé member. Modifiez le rôle ou la règle minimale pour ce que vous souhaitez autoriser pour ce formulaire frontal. N’oubliez pas que même le rôle le plus bas dans WordPress, subscriber, a accès à la modification de son profil dans le panneau d’administration.

Donc, en bref, nous voulons ajouter ces champs sur chaque membre sur cette page frontale personnalisée :

Fonctionnement des formulaires frontaux ACF

Vous devez ajouter deux appels de fonction dans le modèle dont vous voulez le formulaire frontal ; [acf_form_head](https://www.advancedcustomfields.com/resources/acf_form_head/)()et [acf_form](https://www.advancedcustomfields.com/resources/acf_form/)().

La fonction acf_form_head()doit être placée tout en haut de votre modèle, avant toute sortie. Habituellement, dans un modèle, cela signifie avant [get_header](https://developer.wordpress.org/reference/functions/get_header/)(). L’appel de fonction s’assure que tous les scripts et styles sont ajoutés afin que les champs ACF soient rendus correctement, ainsi que toutes les fonctionnalités de traitement, de validation et de soumission du travail. Nous n’avons pas besoin d’ajouter de paramètres à cette fonction.

La acf_form()fonction est celle qui rend le formulaire frontal et doit être placée là où vous souhaitez que le formulaire apparaisse. Il accepte un tableau de paramètres. Nous devons au minimum indiquer quels champs ou groupes afficher et où les enregistrer.

Lorsqu’il s’agit de décider quels champs afficher, vous fournissez généralement un groupe de champs (propriété field_groups). Mais la acf_form()fonction prend également en charge la fourniture de champs uniques spécifiques (propriété fields). Vous pouvez également fournir plusieurs champs ou groupes de champs pour les combiner dans le même formulaire. À cause de cela field_groupsattend un tableau. Ainsi, même si vous ne souhaitez afficher qu’un seul groupe de champs, vous devez fournir cet ID ou ce slug dans un tableau.

La deuxième propriété obligatoire que vous devez fournir au formulaire acf_form()est l’endroit à partir duquel les données doivent être chargées et où elles doivent être enregistrées, dans la propriété post_id. Ne vous laissez pas berner par le nom «poste ». Les règles pour post_idsont les mêmes lorsque vous utilisez get_field(), si vous êtes habitué à travailler avec ACF auparavant. Si les champs sont destinés à une publication (publication, page, publication de type de publication personnalisée), vous n’avez qu’à fournir l’ID ici. Mais si vous souhaitez charger et mettre à jour des données sur les utilisateurs, vous devez suivre ce format : user_{user ID}. De même avec les champs pour une catégorie: category_{category ID}. Consultez toutes les règles sous la rubrique "Obtenir une valeur à partir de différents objets" dans la documentation d’ACF surget_field().

Ajout du formulaire frontal ACF à notre modèle

Nous ajoutons acf_form_head()d’abord le tout en haut, juste avant get_header()– mais après la déclaration du modèle de page (ligne #3). Ensuite, à l’endroit où nous voulons rendre le formulaire, nous ajoutons acf_form()deux propriétés.

Nous devons trouver notre ID de groupe de champs. Si vous avez ajouté le groupe de champs par code (j’ai un article qui explique en détail comment ajouter des champs ACF par code ), vous avez déjà fourni un slug de groupe de champs. Vous fournissez ensuite le slug à la field_groupspropriété, dans un tableau. Si vous avez ajouté le groupe de champs dans le panneau d’administration, vous devez ouvrir le groupe dans le navigateur et vérifier l’URL. Nous sommes intéressés par l’identifiant qui apparaît après " ?post=" :

Dans mon exemple, l’ID est 1145. Alors c’est ce que je fournis dans le tableau de field_groups.

PS: Je ne recommande pas de coder en dur un ID car cet ID sera différent dans chaque instance WordPress! Si vous travaillez sur une installation locale ainsi que sur un serveur intermédiaire et de production, je vous recommande vivement d’ajouter les champs par code à la place. De cette façon, vous pouvez définir un nom de groupe de champs et cela fonctionnera partout.

En ce qui concerne la post_idpropriété, je peux obtenir l’ID utilisateur actuel à l’aide de la fonction WordPress [get_current_user_id](https://developer.wordpress.org/reference/functions/get_current_user_id/)(). Je concatène la chaîne ‘ user_‘ et le retour de cette fonction en tant que post_id.

Et c’est fondamentalement ça!

Si je visite cette page en tant qu’utilisateur membre, j’obtiendrai les valeurs actuelles de cet utilisateur. Tous les types de champs ACF fonctionnent et semblent bons. Et je peux mettre à jour les valeurs à l’aide du formulaire frontal et voir qu’elles sont également mises à jour dans l’administration.

Personnaliser davantage le formulaire

Nous pouvons encore ajuster les paramètres passés à acf_form(). Reportez-vous à la documentation d’ACF sur acf_form() pour voir tous les paramètres possibles.

Pour le moment, notre formulaire de profil utilisateur affiche "Publier mis à jour" lorsque les paramètres sont soumis. Cela n’a pas de sens pour les paramètres de profil. Nous pouvons personnaliser le message avec la propriété updated_message.

Si vous le souhaitez, vous pouvez définir une URL différente vers laquelle rediriger après la soumission du formulaire. Par défaut, la même page se recharge avec le paramètre GET ‘ ?updated=true‘. Vous pouvez spécifier une URL spécifique vers une page de remerciement ou, si le formulaire est destiné à un message, vous souhaiterez peut-être rediriger vers l’affichage de ce message. Nous pouvons fournir l’URL dans la propriété return.

Si nous voulons un texte différent sur le bouton de soumission du formulaire, nous pouvons le spécifier dans la propriété submit_value.

Vous pouvez également dire acf_form()de ne pas rendre la <form>balise. Si vous souhaitez combiner le formulaire d’ACF avec votre propre formulaire personnalisé, vous pouvez définir et saisir le formet manuellement. Si vous faites cela, ACF pourra toujours mettre à jour les valeurs, mais vous devez prendre soin de mettre à jour tous les autres champs de votre formulaire personnalisé.false``<form>``<input type="submit"/>

Déclencher des actions lors de la soumission de formulaires

Parfois, vous souhaiterez peut-être déclencher une fonction ou des événements personnalisés lorsqu’un formulaire frontal est mis à jour. Un exemple courant consiste à écrire une fonction qui envoie une notification par e-mail à chaque soumission de formulaire.

Les champs personnalisés avancés offrent deux crochets utiles lorsque les champs sont mis à jour ; l’action [acf/save_post](https://www.advancedcustomfields.com/resources/acf-save_post/)et le filtre [acf/pre_save_post](https://www.advancedcustomfields.com/resources/acf-pre_save_post/). Encore une fois, ne vous laissez pas berner par le nom "post". Ils sont déclenchés pour toute mise à jour des champs ACF, y compris les champs d’un utilisateur, d’une catégorie, d’un menu, etc.

Le filtre acf/pre_save_postn’est exécuté que sur les formulaires frontaux utilisant acf_form(). En tant que paramètre de ce filtre, nous obtenons post_id, la même valeur que celle que nous avons transmise ci post_id– acf_form()dessus. Le filtre s’attend à ce que vous reveniez post_id. N’oubliez pas que nous devons analyser cela si nous ne faisons pas référence à un ID de publication. Par exemple, pour l’utilisateur, vous devez faire quelque chose comme :

add_filter('acf/pre_save_post', function($post_id) {
    if (strpos($post_id, 'user_') === false) {
        return $post_id;
    }
 
    $user_id = intval(substr($post_id, 5));  // Extracts the user ID
 
    // Do your thing. You'll find the submitted values in $_POST
 
    return $post_id;
});

Vous pouvez également utiliser le crochet acf/save_post– mais rappelez-vous qu’il est également déclenché dans l’administration. En tant que paramètre de ce crochet, vous obtiendrez post_id, comme acf/pre_save_post. Une chose importante à retenir lors de l’utilisation acf/save_postest que vous pouvez utiliser la priorité du hook pour contrôler si votre fonction est exécutée avant l’enregistrement des champs ou après. Une fonction accrochée à la priorité 10 ou supérieure sera déclenchée après l’enregistrement des champs. Et une priorité inférieure à 10 sera déclenchée avant qu’ACF n’enregistre les valeurs.

add_action('acf/save_post', function($post_id) {
    // You can fetch the values with standard get_field()
});
 
add_action('acf/save_post', function($post_id) {
    // You can access the submitted values in $_POST
}, 8);

Lorsque vous avez accroché la fonction avant l’enregistrement (priorité inférieure à 10), vous pouvez comparer les valeurs soumises avec ce qu’ACF enregistrera. Vous pouvez faire get_field()pour obtenir la valeur actuelle et les comparer à la valeur correspondante dans $_POST.

Si vous voulez faire quelque chose uniquement lorsque les champs ont été mis à jour en front-end, vous pouvez simplement vérifier si nous sommes en admin avec [is_admin](https://developer.wordpress.org/reference/functions/is_admin/)(). Vous trouverez ci-dessous un exemple de la manière dont vous procéderiez pour configurer les notifications par e-mail lorsqu’un utilisateur met à jour ses paramètres dans le frontal ;

add_action('acf/save_post', function($post_id) {
    if (strpos($post_id, 'user_') === false) {
        return $post_id;
    }
 
    if (is_admin()) {
        return;  // Bail if we are updating in admin
    }
 
    $user_id = intval(substr($post_id, 5));
 
    // Use get_field() to get the saved/submitted values if needed
    // Then use wp_mail() to send an email
});