« Pré-remplissage pour les formulaires de don » est une nouvelle fonctionnalité introduite dans Charitable Pro 1.8.13 qui vous permet de pré-remplir les champs du formulaire de don à l'aide de paramètres d'URL. Lorsqu'un donateur ouvre une page de don avec la chaîne de requête appropriée, des champs tels que le nom, l'e-mail, l'adresse et les champs de formulaire personnalisés (texte, radio, case à cocher, sélection, adresse) peuvent être remplis automatiquement. Ceci est utile pour les campagnes d'e-mailing, les pages de destination ou les liens provenant de systèmes externes où vous souhaitez transmettre des données du donateur ou du contexte dans le formulaire.
Table des matières
Exigences
- Charitable Pro : Version 1.8.13 ou supérieure
- WordPress : Version 6.2 ou supérieure
- PHP : Version 7.4 ou supérieure
Le pré-remplissage par URL doit être activé par campagne (voir ci-dessous). Il fonctionne à la fois avec le formulaire de don standard et le Constructeur de formulaires visuels(champs personnalisés, champs d'adresse, radio, case à cocher, sélection).
Activation du pré-remplissage par URL
- Modifiez la campagne dont vous souhaitez pré-remplir le formulaire de don.
- Ouvrez le Constructeur de campagnes (ou la zone de formulaire/paramètres où le formulaire de don est configuré).
- Trouvez le bouton bascule Activer le pré-remplissage par URL (dans les options d'affichage du formulaire, près de Activer le formulaire visuel).
- Activez Activer le pré-remplissage par URL et enregistrez la campagne.
Si le pré-remplissage par URL est désactivé pour la campagne, les paramètres de requête sont ignorés et aucun champ n'est pré-rempli. Lorsqu'il est activé, seuls les paramètres qui correspondent aux clés de champ autorisées et qui réussissent la validation sont utilisés.
Format des paramètres
- Préfixe : Par défaut, tous les paramètres de pré-remplissage doivent utiliser le préfixe
cf_.
Exemple :?cf_first_name=Jane&cf_last_name=Doe - Clé de champ : Après le préfixe, le nom du paramètre doit correspondre à la clé du champ du formulaire (par exemple
first_name,last_name,email, ou des clés de champ personnalisées telles quefield_7pour les champs du formulaire visuel). - Valeur : La valeur est assainie selon le type de champ (texte, e-mail, URL, zone de texte, etc.). Les valeurs qui échouent à l'assainissement ou dépassent la longueur maximale sont rejetées.
URL d'exemple :
https://yoursite.com/campaigns/my-campaign/?cf_first_name=Jane&cf_last_name=Doe&[email protected]Facultatif : Vous pouvez supprimer l'exigence du préfixe cf_ en utilisant le filtre charitable_prefill_use_prefix (voir Ressources pour les développeurs). Dans ce cas, des paramètres comme ?first_name=Jane seraient lus. L'utilisation du préfixe est recommandée pour éviter les conflits avec d'autres plugins ou les variables de requête WordPress.
Types de champs pris en charge
Le pré-remplissage est pris en charge pour les types de champs ci-dessous, et uniquement ceux-ci. Un type de champ qui n'est pas listé ignore le paramètre.
- Champs de texte – Texte sur une seule ligne (nettoyé en tant que texte).
- Masqué – Transporte une valeur que vous fournissez plutôt qu'une valeur que le donateur saisit. Adressé par son Nom de champ plutôt que par un ID de champ, donc un champ masqué nommé
sourceest rempli par?cf_source=. Nécessite Charitable Pro 1.8.18 ou une version ultérieure. - Boutons radio – Une valeur d'option ; la valeur de l'URL doit correspondre à une valeur d'option pour la sélectionner.
- Cases à cocher – Une ou plusieurs valeurs d'option. Utilisez une liste séparée par des virgules dans un seul paramètre pour présélectionner plusieurs options (par exemple :
cf_my_checkbox=opt1,opt2). - Sélectionner – Valeur d'option unique (ou la valeur sélectionnée pour les listes déroulantes à sélection unique). Pour la sélection multiple, comportement similaire séparé par des virgules que pour les cases à cocher, le cas échéant.
- Champs d'adresse – Les sous-champs sont pris en charge avec les clés :
address,address_2,city,state,postcode,country.
Exemple :?cf_address=123+Main+St&cf_city=Boston&cf_state=MA&cf_postcode=02101&cf_country=US
Comportement supplémentaire :
- E-mail – Les noms de paramètres contenant
email(par exemple :user_email,email) sont nettoyés avecsanitize_email(). - URL / site web – Les clés telles que
url,website, ou contenant_urlsont nettoyées avecesc_url_raw(). - Champs de type zone de texte – Les clés telles que
message,comment,notes,description,special_messageutilisentsanitize_textarea_field().
Les champs qui ne sont jamais pré-remplis (sécurité) incluent : campaign_id, donation_amount, amount, gateway, password, les champs de paiement et de nonce, ainsi que d'autres clés sensibles ou internes. La liste complète peut être étendue ou modifiée par les développeurs (voir Ressources pour les développeurs).
Noms des paramètres et exemples
Champs courants du donateur
| Paramètre | Description | Valeur d'exemple |
|---|---|---|
prénom | Prénom du donateur | Jane |
nom_de_famille | Nom de famille du donateur | Doe |
email_utilisateur | Email du donateur | [email protected] |
email | Clé d'e-mail alternative (si le formulaire l'utilise) | [email protected] |
Champs d'adresse
| Paramètre | Description | Valeur d'exemple |
|---|---|---|
adresse | Adresse ligne 1 | 123 Main St |
adresse_2 | Adresse ligne 2 | Appt 4 |
ville | Ville | Boston |
état | État/région | MA |
code_postal | Code postal/ZIP | 02101 |
pays | Code pays | US |
Champs personnalisés du formulaire visuel
- Les champs personnalisés dans le Visual Form Builder utilisent des clés internes comme
field_7(où7est l'ID du champ). Utilisez la même clé avec le préfixecf_.
Exemple :?cf_field_7=Ma+valeur - Dans certains contextes, l'ID numérique est également accepté (par exemple,
cf_7peut correspondre àfield_7). Préférezcf_field_Npour plus de clarté lorsque cela est documenté par votre formulaire. - Les champs masqués sont l'exception. Un champ masqué est adressé par le Nom du champ que vous avez tapé dans le constructeur, pas par un ID de champ. Un champ nommé
sourceest rempli par?cf_source=spring-appeal. Le même nom est utilisé pour l'entrée du formulaire, le paramètre et la clé sous laquelle la valeur est stockée après le don, il n'y a donc qu'un seul nom à retenir. Les URL complètes sont acceptées, vous pouvez donc passer une adresse référente entière plutôt qu'un slug.
Radio et sélection
- Utilisez la valeur d'option exacte qui apparaît dans le formulaire.
Exemple : pour un champ de sélection « Pays » avec la valeurUS, utilisez?cf_country=US.
Case à cocher (multiple)
- Utilisez un seul paramètre avec des valeurs d'option séparées par des virgules.
Exemple : pour un champ de cases à cocher avec les optionsnewsletteretupdates, utilisez?cf_interests=newsletter,updates(remplacezinterestspar la clé de votre champ).
URL d'exemple complète
https://yoursite.com/donate/?cf_first_name=Jane&cf_last_name=Doe&cf_user_email=jane%40example.com&cf_address=123+Main+St&cf_city=Boston&cf_state=MA&cf_postcode=02101&cf_country=USUtilisez un encodage URL approprié (par exemple, %20 pour l'espace, %40 pour @ dans un e-mail).
Sécurité et limites
- Clés bloquées : Les clés sensibles et internes (par exemple,
donation_amount,gateway,password, nonces) ne sont jamais lues depuis l'URL. Le montant du don et la méthode de paiement ne peuvent pas être pré-remplis via la chaîne de requête. - Paramètres max : Le nombre de paramètres de pré-remplissage lus depuis l'URL est limité (par défaut 20). Cela peut être modifié avec le filtre
charitable_prefill_max_params. - Longueur max : Chaque valeur est tronquée à une longueur maximale (par défaut 500 caractères). Cela peut être modifié avec le filtre
charitable_prefill_max_value_length. - Assainissement : Toutes les valeurs sont assainies par type de champ (texte, e-mail, URL, zone de texte). Les résultats invalides ou vides après assainissement ne sont pas appliqués.
- Par campagne : Le pré-remplissage ne s'exécute que lorsque Activer le pré-remplissage par URL est activé pour cette campagne. Aucun pré-remplissage n'est appliqué aux campagnes pour lesquelles il est désactivé.
Où trouver la valeur par la suite
Une valeur pré-remplie est enregistrée avec le don. Il y a trois endroits pour la relire.
- L'écran des détails du don. Ouvrez le don dans Charitable > Dons et regardez le panneau de résumé sur la droite. Le champ apparaît sous son libellé avec la valeur capturée.
- L'exportation CSV des dons. Dans Charitable > Dons, ouvrez le panneau d'exportation et le champ apparaît sous Champs personnalisés des formulaires visuels. Une fois son option d'exportation activée, la valeur arrive dans sa propre colonne, intitulée du libellé du champ.
- Directement, pour les développeurs. La valeur est stockée en tant que métadonnées de publication sous le nom propre du champ sans préfixe, donc un champ nommé
sourcedevient la métadonnée de publicationsource.
Choisir où elle apparaît
La section Options avancées de chaque champ dans le Constructeur de campagne contrôle cela.
| Option | Ce qu'il fait | Défaut pour un champ masqué |
|---|---|---|
| Activer dans l'exportation | Ajoute une colonne à l'exportation CSV des dons | Activé |
| Activer dans les métadonnées du don | Affiche la valeur sur l'écran des détails du don | Activé |
| Activer les balises d'e-mail | Crée une balise d'e-mail à utiliser dans les modèles d'e-mail | Désactivé |
| Envoyer dans les Webhooks d'automatisation | Inclut le champ dans les charges utiles de connexion d'automatisation | Désactivé |
Les deux options par défaut sont activées pour un champ masqué, car un champ dont le but est de transmettre des informations n'est pas très utile si ces informations ne peuvent pas être relues.
Un champ masqué créé avant Charitable Pro 1.8.18 est l'exception. Les versions antérieures n'avaient aucun contrôle pour cela et stockaient un réglage « désactivé » pour chaque champ masqué, donc Charitable le traite comme votre préférence plutôt que de le remplacer. Pour commencer à exporter l'un de ces champs, ouvrez-le dans le Constructeur de campagne, développez Options avancées, et activez Activer dans l'exportation. Les champs masqués ajoutés à partir de la version 1.8.18 sont exportés par défaut.
Un champ qui n'a rien capturé
Un champ qui n’a capturé aucune valeur n’écrit aucune ligne, plutôt qu’une ligne vide. Si vous attendez une valeur et que le champ est totalement absent du don, la valeur n’est pas arrivée. Vérifiez d’abord le commutateur de pré-remplissage de l’URL de la campagne, puis que le nom du paramètre correspond exactement au nom du champ.
Enregistrer automatiquement la page référente
Si vous souhaitez que la page référente soit enregistrée sans ajouter de paramètre à chaque lien, placez la balise de fusion {referrer} dans la Valeur du champ d’un champ masqué au lieu d’utiliser un paramètre d’URL. Charitable remplit ceci dans le navigateur, à partir de la page d’où le donateur est arrivé.
Le remplir dans le navigateur plutôt que sur le serveur est ce qui le rend sûr sur un site mis en cache. Une valeur calculée sur le serveur est stockée dans le cache de votre page avec le reste de la page, de sorte que chaque donateur après le premier serait enregistré comme venant de l’endroit d’où le premier est venu. Parce que le navigateur le remplit, il fonctionne également à l’intérieur d’une fenêtre modale de don. Rien n’est enregistré pour un visiteur dont le JavaScript est désactivé, ce qui est délibéré : un blanc est plus utile qu’une réponse assurément fausse sur l’origine d’un don.
Dépannage
Les champs ne sont pas pré-remplis
- Confirmez que Activer le pré-remplissage par URL est activé pour la campagne (Constructeur de campagne → options du formulaire).
- Vérifiez que l'URL utilise le préfixe
cf_(par exemple,cf_first_name, et nonfirst_name) sauf si vous avez désactivé le préfixe via un filtre. - Assurez-vous que le nom du paramètre correspond à la clé du champ (par exemple,
user_emailouemailpour le champ e-mail,field_7pour un champ personnalisé avec l'ID 7). - Pour les champs de sélection/radio/case à cocher, la valeur doit correspondre exactement à une valeur d'option dans le formulaire.
La valeur est tronquée ou vide
- Les valeurs sont tronquées à la longueur max (500 caractères par défaut). Utilisez le filtre
charitable_prefill_max_value_lengthsi vous avez besoin de valeurs plus longues. - Si la valeur est vide après la désinfection (par ex. email invalide), elle ne sera pas appliquée. Vérifiez l'encodage (par ex.
%40pour@dans les emails).
Les sous-champs d'adresse ne se remplissent pas
- Utilisez les clés exactes :
address,address_2,city,state,postcode,country. Elles sont préfixées comme les autres paramètres :cf_address,cf_city, etc. - Assurez-vous que le formulaire de la campagne inclut bien des champs d'adresse et que le pré-remplissage par URL est activé pour la campagne.
Champs personnalisés du formulaire visuel
- Utilisez le format de clé
field_N(par ex.cf_field_7) où N est l'ID du champ personnalisé. Vérifiez le constructeur de formulaires ou inspectez les attributsnamedu formulaire pour confirmer les ID.
Ressources pour les développeurs
Filtres
- charitableprefilluse_prefix –
apply_filters( 'charitable_prefill_use_prefix', true )
Retournefalsepour autoriser les paramètres sans le préfixecf_(par ex.?first_name=Jane). Par défauttrue. - charitableprefillenabled –
apply_filters( 'charitable_prefill_enabled', $enabled, $campaign_id )
Remplace si le pré-remplissage par URL est activé pour une campagne. Retournetrueoufalse; retournenullpour utiliser le paramètre enregistré de la campagne. - charitableprefillmax_params –
apply_filters( 'charitable_prefill_max_params', 20 )
Nombre maximum de paramètres d'URL à lire pour le pré-remplissage. Par défaut20. - charitableprefillmaxvaluelength –
apply_filters( 'charitable_prefill_max_value_length', 500, $field_key )
Longueur maximale de caractères par valeur. Par défaut500. - charitableprefillblocked_keys –
apply_filters( 'charitable_prefill_blocked_keys', $blocked_keys )
Ajouter ou supprimer des clés qui ne doivent jamais être pré-remplies depuis l'URL (par ex. noms de champs sensibles à la sécurité). - charitableprefillsanitize_value –
apply_filters( 'charitable_prefill_sanitize_value', $sanitized, $field_key, $value )
Modifier la valeur désinfectée avant qu'elle ne soit appliquée au champ.
Classe et méthodes
- CharitableFormPrefill::get_instance() – Retourne l'instance singleton.
- getprefillvalues( $campaign_id ) – Retourne un tableau de toutes les valeurs de pré-remplissage analysées (clé_champ => valeur) pour la requête et la campagne actuelles.
- getvalue( $key, $campaignid ) – Retourne la valeur de pré-remplissage pour une seule clé de champ, ou
nullsi non définie. Gère le mappage des champs personnalisés du formulaire visuelfield_N/ clé numérique. - isenabledpourcampaign( $campaignid ) – Indique si le préremplissage d’URL est activé pour la campagne donnée.
- hasprefillparams() – Renvoie si la requête actuelle contient des paramètres de pré-remplissage dans l'URL (utile pour un abandon précoce).
- reset() – Efface les valeurs analysées mises en cache (par exemple, pour les tests).
Historique des versions
| Version | Modifications |
|---|---|
| 1.8.13 | Chaîne de requête URL pour le pré-remplissage des champs du formulaire de don (texte, radio, case à cocher, sélection, adresse). Préfixe cf_ , bascule par campagne, assainissement par type de champ, clés bloquées et filtres. |
| 1.8.18 | Les champs masqués peuvent être pré-remplis, adressés par leur nom de champ. Les valeurs capturées sont maintenant affichées sur l’écran des détails du don et peuvent être incluses comme colonne d’exportation CSV des dons, contrôlées par champ dans les Options avancées. Ajoute la balise de fusion {referrer} pour les champs masqués. |
Pour construire le formulaire de don et les champs personnalisés, consultez le Générateur de formulaires visuels et la documentation du formulaire de don.
