Tutoriel : créer un type de champ de formulaires de gravité personnalisés avancés et comment gérer plusieurs valeurs d’entrée

Dans ce didacticiel, je vais vous montrer comment créer un type de champ Gravity Forms personnalisé avancé. Le champ aura plusieurs entrées et nécessitera un traitement spécial afin de stocker et d’afficher les valeurs soumises.

Ce que nous ferons

Dans cet exemple, je suppose un exemple de propriétaire de site Web WordPress qui s’occupe des livraisons de déjeuners sur un lieu de travail. Le propriétaire a un formulaire pour que les gens remplissent le type de déjeuner qu’ils veulent et combien pour chaque jour de la semaine. Cela peut être résolu comme une méthode semblable à un tableau pour entrer un numéro pour n’importe quel cours à n’importe quel jour où ils veulent être livrés.

Les cours sont modifiables dans les paramètres du champ dans l’éditeur de formulaire et peuvent être modifiés à tout moment. Et pour chaque soumission de formulaire, le propriétaire du site Web obtient un aperçu complet des valeurs soumises :

Évidemment, ce n’est qu’un exemple et vous devrez probablement l’adapter à votre cas. Mais avec cet exemple, nous avons la chance d’apprendre à gérer plusieurs entrées dans un seul champ. Cela devrait vous donner quelques idées sur la façon de gérer votre propre type de champ personnalisé.

Avant de commencer à coder

Avant de commencer, nous avons besoin d’un endroit pour ajouter notre code. Vous pouvez l’ajouter dans votre thème functions.phpou dans votre fichier de plugin.

La méthode que j’ai choisie est orientée objet, ce qui signifie créer une classe qui étend la GF_Fieldclasse de Gravity Forms. Je recommande de mettre la classe dans un fichier séparé dans votre projet. Vous devez également vérifier que le plugin Gravity Forms existe avant d’inclure votre classe pour éviter de planter votre site.

Si vous êtes intéressé, vous pouvez consulter la documentation de Gravity Forms sur GF_Field. Vous trouverez d’autres fonctions et variables dont vous pourriez avoir besoin pour votre type de champ.

En étendant la GF_Fieldclasse, nous pouvons simplement choisir de remplacer les fonctions que nous devons modifier. En ce qui concerne les fonctions que nous ne remplaçons pas, Gravity Forms exécutera la valeur par défaut définie dans GF_Field. Dans le didacticiel ci-dessous, nous allons passer en revue chaque fonction que nous devons remplacer pour notre champ personnalisé une par une. Sans plus tarder, commençons !

Création d’un type de champ personnalisé

La première étape consiste à définir une classe PHP personnalisée qui étend GF_Field. Donnez à la classe un nom unique et assurez-vous qu’elle est incluse dans votre projet. Après la définition de la classe, nous exécutons la register()fonction statique en GF_Fieldpassant une instance de notre classe en paramètre. Cela initialise notre classe et enregistre le type de champ.

La seule variable obligatoire dont vous avez besoin dans votre classe est $type. La variable de classe $typedoit être unique et est un nom de slug de votre type de champ. Dans mon exemple, je l’ai nommé ‘ food_delivery‘.

if (class_exists('GF_Field')) {
    class FoodDelivery extends GF_Field {
        public $type = 'food_delivery';
 
        // The rest of the code is added here...
    }
    GF_Fields::register(new FoodDelivery());
}

Avec ce petit morceau de code, notre type de champ personnalisé doit être ajouté en tant que choix disponible dans l’éditeur Gravity Forms. Par défaut, il apparaît à la fin de la boîte "Champs standard". Parce que nous n’avons pas encore donné de nom à notre champ (c’est la prochaine étape), le bouton est étiqueté comme la valeur de $type.

Définir le nom du champ

La prochaine étape est facile; simplement donner à notre domaine un meilleur nom. Pour ce faire, nous redéfinissons la fonction get_form_editor_field_title(). Tout ce que nous avons à faire est de renvoyer une chaîne avec le nom du champ.

public function get_form_editor_field_title() {
    return esc_attr__('Food Delivery', 'txtdomain');
}

Avec cette fonction dans notre classe, le bouton pour ajouter le champ est mis à jour avec une bien meilleure étiquette.

Modification de la catégorie de champ

Cette étape est facultative. Par défaut, notre type de champ personnalisé apparaît dans la case "Champs standard", mais nous pouvons le modifier. Supposons que nous voulions qu’il apparaisse à la place dans la boîte "Champs avancés".

Pour changer la catégorie dans laquelle nous voulons que le champ apparaisse, nous remplaçons la fonction get_form_editor_button(). Nous devons retourner un tableau associatif avec deux éléments. En tant que valeur de la clé ‘ group‘, vous fournissez le nom interne de la catégorie dans laquelle vous souhaitez que le bouton apparaisse. Les options disponibles ici sont ‘ standard_fields‘, ‘ advanced_fields‘, ‘ post_fields‘ ou ‘ pricing_fields‘. (Vous pouvez également créer votre propre catégorie, mais cela n’est pas couvert ici). Le deuxième élément du tableau a besoin de la clé ‘ text‘ et pour cela nous renvoyons simplement le nom du champ en appelant get_form_editor_field_title(). C’est la fonction que nous venons de créer ci-dessus.

Maintenant, le bouton pour ajouter notre type de champ personnalisé est déplacé dans la case "Champs avancés".

Activation des paramètres de champ

Si vous avez essayé d’ajouter le type de champ dans un formulaire, vous avez peut-être remarqué qu’il n’y a aucun paramètre. Vous ne pouvez même pas modifier l’étiquette. La façon dont cela fonctionne est que tous les types de paramètres sont réellement là, ils sont simplement tous cachés avec CSS par Gravity Forms. Nous devons définir individuellement les paramètres que nous voulons activer, et Gravity Forms affichera alors les paramètres choisis pour nous.

Nous devons définir la fonction get_form_editor_field_settings()et renvoyer un tableau de tous les paramètres que nous ne voulons pas masquer pour notre type de champ. Les paramètres que vous souhaitez ajouter dépendent entièrement de vous et de votre projet. Gardez à l’esprit que votre champ doit prendre en charge tous les paramètres que vous activez, sinon cela n’a aucun sens d’afficher un paramètre pour celui-ci.

J’ai créé un aperçu rapide des noms des paramètres ci-dessous. C’est loin d’être une liste complète – car il y a beaucoup de paramètres qui ne sont pratiquement utiles que pour des types de champs très spécifiques. Par exemple, le format de téléphone, le format de date/heure et tout un tas de paramètres liés aux champs de publication et aux champs de tarification.

Onglet Général

• Libellé du champ :label_setting
• Descriptif du champ :description_setting
• Les choix:choices_setting
• Obligatoire:rules_setting
• Pas de doublons :duplicate_setting
• Activer les colonnes :columns_setting
• Activer le choix "tout sélectionner" :select_all_choices_setting
• Activer le choix "autre":other_choice_setting

Onglet Apparence

• Espace réservé :placeholder_setting
• Visibilité de l’étiquette de champ et emplacement de la description :label_placement_setting
• Message de validation personnalisé :error_message_setting
• Classe CSS personnalisée :css_class_setting
• Taille du champ:size_setting

Onglet Avancé

• Libellé du champ Admin :admin_label_setting
• Valeur par défaut:default_value_setting
• Activer la saisie du mot de passe :password_field_setting
• Forcer SSL :force_ssl_field_setting
• Visibilité:visibility_setting
• Autoriser le remplissage dynamique du champ :prepopulate_field_setting
• Activer la logique conditionnelle :conditional_logic_field_setting
• Activer la logique conditionnelle de la page :conditional_logic_page_setting

Comme pour notre exemple, les plus importants sont l’étiquette du champ, la description, les choix et si oui ou non le champ est obligatoire ou non. Nous autorisons également les paramètres pour la classe CSS, le message de validation personnalisé et la logique conditionnelle.

public function get_form_editor_field_settings() {
    return [
        'label_setting',
        'choices_setting',
        'description_setting',
        'rules_setting',
        'error_message_setting',
        'css_class_setting',
        'conditional_logic_field_setting'
    ];
}

Actualisez l’éditeur de formulaire et vous devriez maintenant voir tous les paramètres et onglets choisis apparaître dans notre champ. Tous les paramètres sont gérés et enregistrés automatiquement par Gravity Forms.

Allez-y et ajoutez quelques éléments dans la liste des choix afin que nous ayons quelque chose avec quoi travailler. Voici ce que j’ai mis en place à titre d’exemple :

Définition des choix par défaut personnalisés

Si vous avez l’habitude d’utiliser, par exemple, des boutons radio ou des cases à cocher dans Gravity Forms, vous avez probablement remarqué qu’ils sont accompagnés de choix tels que "First Choice", "Second Choice", "Third Choice". Il s’agit du comportement par défaut de Gravity Forms si aucun choix n’a été enregistré (avant) et cela ne se déclenche que sur ces types de champs spécifiques. Mais pour notre type de champ personnalisé, aucun choix ne sera rempli. Cela le rend un peu lourd, car vous n’obtiendrez pas le bouton "+" pour ajouter un autre choix. Vous devez utiliser le bouton "Ajouter en bloc/choix prédéfinis", y ajouter des choix, et après cela, vous avez accès aux boutons "+" pour ajouter des choix. Mais il est facile de définir des choix personnalisés – tout ce dont vous avez besoin est de définir une variable de tableau de classepublic $choiceset Gravity Forms générera automatiquement des choix prédéfinis dans votre champ lorsque vous l’ajouterez à vos formulaires.

Remarque: Il s’agit d’une variable de classe, que vous pouvez ajouter en haut de la classe, juste en dessous de public $type. Chaque choix doit être un tableau, avec le choix comme valeur de la clé ‘ text‘.

Gardez à l’esprit que si vous avez déjà ajouté le champ au formulaire, il ne remplira pas rétroactivement les choix. Cela n’entre en vigueur que lorsque vous ajoutez un nouveau champ au formulaire.

Note: Dans Gravity Forms, il semble possible d’ajouter également les touches ‘ value‘ à chaque choix. Mais je n’ai pas réussi à faire fonctionner cela – les valeurs deviendront automatiquement les mêmes que le texte de choix.

Définition de la valeur du champ en tant que tableau

La prochaine étape est assez simple, mais nécessaire. Les valeurs par défaut des champs dans Gravity Forms sont des chaînes. Nous avons besoin que la valeur soit un tableau car nous travaillons avec plusieurs entrées. Pour ce faire, nous définissons la fonction is_value_submission_array()et renvoyons true.

public function is_value_submission_array() {
    return true;
}

Cela garantit que nous pouvons travailler correctement avec la valeur saisie de nos multiples entrées.

Rendu de la sortie de champ

Lorsqu’il s’agit de rendre la sortie du champ, il y a quelques points à prendre en compte.

Tout d’abord, vous devez choisir entre deux fonctions ; get_field_input()ou get_field_content(). Dans la première méthode, Gravity Forms affiche automatiquement l’élément de la liste d’emballage, l’étiquette, la description et le conteneur du message d’erreur de validation dans votre champ et vous ne contrôlez que la sortie du champ interne. Avec la deuxième méthode, rien de tout cela ne se produit et vous contrôlez davantage la sortie du champ. Cependant, vous devez afficher manuellement l’étiquette, la description et les messages d’erreur. La première méthode, get_field_input(), convient parfaitement dans la plupart des cas.

La deuxième chose à savoir est que la fonction de rendu du champ affecte trois emplacements différents. Les trois sont le rendu de la sortie du champ dans l’interface, l’aperçu du champ dans l’éditeur de formulaire et enfin le champ lors de la modification d’une entrée. Heureusement, Gravity Forms propose des fonctions pour déterminer facilement à quelle vue nous en sommes. Habituellement, vous rendrez le champ de la même manière dans les trois cas. Mais parce que le rendu d’une grande table avec beaucoup d’entrées devient inutilement maladroit dans l’éditeur de formulaire, j’ai choisi de rendre le champ différemment dans l’éditeur de formulaire.

Et enfin, nous devons nous assurer que toutes les entrées reçoivent un nameattribut approprié afin que Gravity Forms puisse collecter sa valeur lors de la soumission du formulaire. Toutes les entrées dans Gravity Forms ont besoin d’ nameattributs qui suivent cette règle : name="input_{FIELD_ID}"(les champs à sélection multiple utilisent un ID supplémentaire, mais nous n’avons pas besoin de nous en préoccuper pour notre cas). Nous avons accès au champ ID car il s’agit d’une variable de classe (de GF_Field). Mais dans notre cas, nous avons dit à Gravity Forms que la valeur est un tableau et non une valeur singulière (étape précédente), nous ajoutons donc des crochets après l’attribut name ; name="input_{FIELD_ID}[]". Ainsi, si le champ a l’ID 4 dans un formulaire, l’attribut name doit être " input_4[]".

J’opte pour l’utilisation get_field_input()qui vient avec trois paramètres. Le premier paramètre est l’objet formulaire, dont nous n’avons pas vraiment besoin pour notre exemple. Le deuxième paramètre est la valeur actuelle. Il peut s’agir de la valeur du champ à partir de $_POSTlaquelle le formulaire a été soumis, mais sans succès. Nous pouvons conserver les valeurs soumises précédemment. Ou si la fonction est en cours d’exécution lors de la modification d’une entrée, la valeur sera la valeur stockée à partir de la soumission. Nous traiterons la valeur de plus près plus tard. Et le troisième paramètre est l’objet d’entrée, dont nous n’aurons pas non plus besoin pour notre exemple.

Commençons par implémenter get_field_input()ce qui attend le rendu final sous forme de chaîne. Dès le départ, je décide de renvoyer une chaîne vide si nous sommes à l’intérieur de l’éditeur de formulaire, car je ne veux pas afficher le tableau complet dans cette vue. Nous pouvons utiliser la méthode $this->is_form_editor()pour vérifier si nous sommes ou non dans l’édition du formulaire. Vous pouvez choisir d’ignorer cela ou de rendre autre chose si vous souhaitez un aperçu du champ dans l’éditeur de formulaire.

L’étape suivante consiste à créer le code HTML d’un tableau qui boucle sur un tableau de jours pour générer les colonnes et les lignes pour chaque élément de cours. Mais parce que nous avons besoin d’accéder au tableau de jours (colonnes de table) à plusieurs endroits, nous devons le définir comme une variable de classe, le rendant accessible à partir de toutes les fonctions qu’il contient. Je définis une variable de classe $delivery_daysavec un tableau des jours pour lesquels je souhaite proposer la livraison.

class FoodDelivery extends GF_Field {
    public $type = 'food_delivery';
 
    private $delivery_days = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'];
 
    public function get_form_editor_field_title() {
        ...
}

C’est juste un exemple! Vous voudrez peut-être récupérer le tableau pour les colonnes d’un autre endroit qui n’est pas codé en dur.

Revenons get_field_input()et construisons notre table avec des entrées. D’abord, je boucle sur la variable de classe et génère les en-têtes de tableau. Ensuite, je boucle sur les choix entrés dans le champ de réglage pour les choix. Ceci est accessible à partir de la variable de classe (de GF_Field) $this->choices. Pour chaque choix, je rends une entrée avec les attributs de nom propre. Nous avons accès à l’ID du champ à partir GF_Fieldde la variable de classe de $this->id.

Avec ce code en place, nous devrions obtenir une belle table rendue pour notre type de champ en frontend ! Évidemment, le HTML dépend entièrement de vous, ce n’est qu’un exemple de base.

Nous laissons cette fonction pour l’instant, mais nous y reviendrons plus tard pour gérer la valeur soumise !

Stocker correctement la valeur

À partir de maintenant, Gravity Forms enregistrera notre champ sous la forme d’un tableau unidimensionnel rempli avec les valeurs saisies et les chaînes vides où l’entrée était vide. Il n’y a aucune information sur le jour ou le choix auquel la valeur appartient, autre que l’index. Nous devons transformer ce tableau unidimensionnel en un tableau associatif multidimensionnel où nous stockons le jour et l’étiquette de choix. Nous pouvons alors facilement accéder à la valeur numérique stockée, par exemple $value['Ham sandwich']['Monday']. Après cette transformation de tableau, nous devons également sérialiser le tableau afin que Gravity Forms puisse stocker correctement la valeur dans la base de données.

Nous devrons transformer ce tableau de valeurs à plusieurs endroits, je définirai donc une fonction distincte pour cela. La fonction accepte le tableau unidimensionnel et le transforme en un tableau multidimensionnel avec les valeurs stockées pour les jours et les choix :

Cela stockera les noms de jour et les choix directement dans la valeur du champ. Procéder ainsi permet de modifier les choix ultérieurement sans casser les anciennes entrées.

Passons maintenant au remplacement de la fonction qui gère le stockage de la valeur soumise ; get_value_save_entry(). Il est livré avec cinq paramètres mais nous n’avons besoin que du premier qui est la valeur soumise. À l’intérieur de la fonction, nous transmettons la valeur à notre fonction personnalisée ci-dessus, sérialisons son retour et renvoyons enfin la nouvelle valeur.

À ce stade, Gravity Forms stockera avec succès nos valeurs exactement comme nous les voulons! Cependant, la valeur stockée est maintenant un tableau sérialisé que Gravity Forms se fera un plaisir d’écho directement. Nous devons implémenter des fonctions pour le transformer d’un vilain tableau sérialisé en une jolie sortie partout où nous en avons besoin.

Affichage de la valeur soumise

Il y a trois endroits où nous devons changer la sortie de la valeur de notre champ ; la liste des entrées, en regardant une seule entrée, et dans les balises de fusion de Gravity Forms. Les balises de fusion sont le plus souvent utilisées dans les notifications par e-mail. Par exemple {all_fields}, une balise de fusion affiche les valeurs complètes du formulaire soumis dans les e-mails.

Étant donné que nous rendons la même sortie dans trois cas différents, il est logique de créer une fonction distincte pour celle-ci. J’ai défini une fonction personnalisée qui accepte la valeur ; le tableau multidimensionnel non sérialisé, en paramètre. La fonction construit ensuite du code HTML qui affiche le tableau de manière jolie et renvoie la chaîne. J’ai opté pour une <ul>liste imbriquée, mais vous pouvez modifier la sortie comme vous le souhaitez.

Super, commençons par le premier: la liste des entrées: get_value_entry_list(). Vous pouvez choisir de sortir la sortie complète ici, mais cela peut devenir assez maladroit et long pour la vue de liste, j’ai donc opté pour simplement renvoyer une chaîne fixe qui explique que l’utilisateur doit entrer dans les détails de l’entrée pour voir la vue d’ensemble complète.

public function get_value_entry_list($value, $entry, $field_id, $columns, $form) {
    return __('Enter details to see delivery details', 'txtdomain');
}

Cela dépend bien sûr entièrement de vous, vous pouvez opter pour n’afficher que le premier x nombre de caractères par exemple.

La deuxième fonction est celle affectant la vue d’une seule entréeget_value_entry_detail() :

Nous désérialisons simplement le tableau avec la fonction de WordPress [maybe_unserialize](https://developer.wordpress.org/reference/functions/maybe_unserialize/)()et renvoyons la sortie de chaîne de notre fonction personnalisée.

La dernière fonction affecte les balises de fusion et s’assure que la valeur de notre champ s’affiche également bien dans les e-mails : get_value_merge_tag().

Notez que nous n’aurons pas besoin de désérialiser la valeur à l’intérieur de cette fonction.

Avec ces trois fonctions en place, toutes les valeurs soumises devraient être jolies partout ! Par exemple, lors de l’affichage d’une entrée soumise :

Cependant, il manque une chose importante! À ce stade, nos entrées ne conservent pas les valeurs précédemment soumises et c’est plutôt mauvais.

Faire en sorte que nos entrées conservent la valeur précédemment soumise

Il existe principalement deux cas où nous devons nous assurer que les entrées conservent les valeurs précédemment soumises. Le premier cas est lorsqu’une soumission de formulaire a échoué (par exemple, l’utilisateur a oublié un champ obligatoire). À l’heure actuelle, toutes nos entrées perdent toutes les valeurs précédemment saisies et l’utilisateur doit saisir à nouveau toutes les valeurs. Deuxièmement, lorsque le propriétaire du site modifie une entrée, les entrées ne sont pas renseignées avec les valeurs soumises à partir de la soumission, ce qui rend quasiment impossible la modification correcte des valeurs.

Pour résoudre ce problème, nous retournons à la fonction get_field_input(). Le deuxième paramètre de cette fonction est la valeur. Mais rappelez-vous que cette fonction affecte à la fois le rendu frontal et l’édition d’entrée. Ceci est important car la valeur stockée est différente dans ces deux cas. Si nous sommes à l’interface et que nous traitons la soumission du formulaire, la valeur est au format du tableau unidimensionnel mentionné précédemment. Et si nous modifions une entrée, la valeur est au format d’un tableau multidimensionnel sérialisé. Nous devons donc traduire correctement la valeur fournie dans get_field_input()pour accéder facilement aux valeurs réelles.

Dans le code ci-dessus, avant de commencer à créer le HTML pour la sortie du champ, nous créons une variable $table_valuequi contient la valeur correctement traduite. Nous utilisons GF_Fieldla fonction is_entry_detail()de pour vérifier si nous modifions ou non une entrée. Et puis pour nos entrées, il est facile d’accéder aux valeurs appropriées et de les définir comme valueattributs des entrées :

Avec la mise à jour ci-dessus get_field_input(), toutes nos entrées personnalisées doivent toujours être renseignées avec la valeur précédente ; qu’il s’agisse de modifier une entrée ou de réessayer de soumettre un formulaire.

À ce stade, tout ce qui concerne le rendu et le stockage de nos valeurs est terminé et fonctionne pleinement. Mais il y a encore une chose que nous devons absolument corriger.

Faire passer notre champ de validation "obligatoire"

Gravity Forms a des contrôles pour voir si la valeur d’un champ est vide ou non. Cela est souvent nécessaire lorsque le champ est défini comme requis. Lorsqu’un champ est obligatoire, vous ne pouvez pas soumettre le formulaire s’il est vide, n’est-ce pas ? Le problème pour nous est que nous avons plusieurs entrées et nous voulons permettre à certaines d’entre elles d’être vides. Cela devient un problème si notre champ est défini sur requis. Malheureusement, Gravity Forms interprète mal "est-ce vide" et exige que toutes les entrées soient remplies. Nous devons donc ajouter une règle qui dit que si au moins une de nos nombreuses entrées est remplie, la valeur totale du champ n’est pas vide.

La dernière fonction que nous devons remplacer dans notre classe est is_value_submission_empty(). Nous obtenons uniquement l’ID de formulaire en tant que paramètre de cette fonction, nous devons donc extraire la valeur du champ en utilisant la fonction Gravity Forms pour l’extraire du $_POSTtableau : rgpost('input_<FIELD ID>'). Le retour devrait être le tableau unidimensionnel que nous avons vu auparavant. Tout ce que nous avons à faire est de parcourir le tableau et de revenir falsesi nous trouvons une valeur quelque part. Sinon on revient truecar la valeur du champ est en effet complètement vide.

Avec la fonction ci-dessus en place, notre champ n’échouera pas la soumission s’il est défini sur requis et qu’au moins une entrée est remplie.

Conclusion et code final

Ce didacticiel vous a montré en détail comment créer votre propre type de champ avancé personnalisé pour Gravity Forms. Même si votre projet est différent de mon exemple, j’espère que vous avez des conseils et des a-ha en cours de route. Je trouve que la documentation de Gravity Forms fait défaut dans certains cas, et c’est le résultat de beaucoup d’essais et d’erreurs ! En tout cas, j’espère que cela vous a été utile !

Pour référence, voici le code complet dans son intégralité :