« 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 :
- Champs de texte – Texte sur une seule ligne (nettoyé en tant que texte).
- 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.
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é.
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. |
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.
