L'API des champs de don offre un moyen puissant et flexible d'ajouter, de supprimer et de modifier vos champs de don.

• Que sont les champs de don ?
• Comment obtenir la valeur d'un champ particulier ?
• Comment ajouter un nouveau champ à mon formulaire de don ?
• Comment modifier un champ de don existant ?
• Comment ajouter un champ de don à une campagne spécifique ?
• Comment modifier un champ de don pour une campagne particulière ?
• Comment faire apparaître un champ de manière conditionnelle ?
• Liste complète des champs de don par défaut

Que sont les champs de don ?

Les champs de don sont toutes les informations sur un don que vous pouvez utiliser. Par exemple, voici certains des champs disponibles par défaut :

• first_name – Obtenir le prénom du donateur.
• last_name – Obtenir le nom de famille du donateur.
• amount_formatted – Obtenir le montant du don, formaté selon les paramètres de devise de votre site (par exemple, 50,00 $).
• date – La date à laquelle le don a été effectué.
• gateway_label – Le mode de paiement utilisé par le donateur.

Comment obtenir la valeur d'un champ de don particulier ?

Vous pouvez obtenir la valeur de n'importe quel champ de don via l'objet Charitable_Donation du don.

La première étape consiste à obtenir un objet Charitable_Donation :

$donation_id = 123; // Replace with your Donation's ID.
$donation    = charitable_get_donation( $donation_id );

Ensuite, vous pouvez obtenir la valeur du champ en appelant get() sur l'objet, comme vous pouvez le voir dans les exemples ci-dessous :

$first_name = $donation->get( 'first_name' );
$date       = $donation->get( 'date' );
$gateway    = $donation->get( 'gateway_label' );

Pour tout mettre ensemble :

$donation_id = 123;
$donation    = charitable_get_donation( $donation_id );
$first_name  = $donation->get( 'first_name' );

Comment ajouter un nouveau champ à mon formulaire de don ?

L'ajout d'un nouveau champ est un processus en deux étapes.

Premièrement, vous créerez un nouvel objet Charitable_Donation_Field qui définira les paramètres de votre champ : son libellé, le type de valeur qu'il stocke, comment il doit être inclus dans le formulaire de don (le cas échéant), s'il doit être ajouté au fichier d'exportation des dons, et plus encore.

Ensuite, vous ajouterez ce champ à la classe Charitable_Donation_Field_Registry, qui fournit un moyen de stocker et de récupérer les champs de don.

Voyons comment cela fonctionne dans un exemple :

/**
 * Create a callback function on the `init` hook, where we
 * can register our donation field.
 */
add_action( 'init', function() {

    /* Create the `Charitable_Donation_Field` object. */
    $field = new Charitable_Donation_Field(
        'my_custom_field',
        array(
            'label'          => __( 'My Custom Field' ),
            'data_type'      => 'meta', 
            'donation_form'  => array(
                'type'       => 'text',
                'required'   => false,
                'show_after' => 'phone',
            ), 
            'admin_form'     => true,
            'show_in_meta'   => true,
            'show_in_export' => true,
            'email_tag'      => array(
                'description' => __( 'The custom field value' ),
            ),
        )
    );

    /* Get the `Charitable_Donation_Field_Registry` instance. */
    $fields = charitable()->donation_fields();

    /* Add the new field. */
    $fields->register_field( $field );
} );

Dans l'exemple ci-dessus, nous avons créé un nouveau champ avec la clé my_custom_field. Voici ce que signifient ses paramètres définis :

• Son libellé est « Mon champ personnalisé ». C'est ce qui sera utilisé dans le formulaire de don, dans la zone des détails des dons de l'administrateur et dans l'exportation des dons comme en-tête de colonne.
• Son type de données est meta. Cela signifie qu'il sera stocké en tant que champ méta spécifique à ce don.
• Il est configuré pour être affiché dans le formulaire de don, juste après le champ phone. C'est un champ facultatif.
• Il sera également ajouté au formulaire de don de l'administrateur.
• Lors de la visualisation des détails du don, vous pourrez voir ce que le donateur a saisi pour ce champ dans la section « Détails du don ».
• Lorsque vous téléchargez un export des dons, une nouvelle colonne « Mon champ personnalisé » sera ajoutée, indiquant ce que les donateurs ont saisi pour ce champ.
• Une nouvelle balise d'e-mail a été créée pour ce champ, vous pouvez donc facilement l'inclure dans les e-mails spécifiques aux dons, tels que le reçu de don (pour les donateurs) ou la notification de don (pour les administrateurs).

C'est un exemple relativement simple, mais il accomplit beaucoup. Cliquez ici pour une description plus détaillée de tous les paramètres disponibles lors de la création d'objets Charitable_Donation_Field.

Comment modifier un champ de don existant ?

Pour modifier un champ de don existant, vous récupérez d'abord le champ du Charitable_Donation_Field_Registry, puis vous mettez à jour la valeur du champ.

Pour mettre à jour la valeur du champ, nous pouvons appeler set() sur le champ, ou utiliser le setter magique.

/**
 * Create a callback function on the `init` hook, where we
 * can start changing the donation field.
 */
add_action( 'init', function() {

    /* Get the Donation Field Registry object. */
    $fields = charitable()->donation_fields();

    /* Get the field we want to change. */
    $field  = $fields->get_field( 'phone' );
    
    /**
     * Change #1: Make it a required field (uses set()).
     * Change #2: Change the label (uses magic setter).
     */
    $field->set( 'donation_form', 'required', true );
    $field->label = 'Phone Number';
} );

Pour plus d'informations sur la façon de mettre à jour les arguments de champ, consultez la référence détaillée de ces méthodes de classe :

• Charitable_Donation_Field::set()
• Charitable_Donation_Field::__set() (setter magique).

Comment ajouter un champ à un formulaire de don spécifique à une campagne ?

Si vous souhaitez qu'un champ nouveau ou existant ne s'affiche que pour certaines campagnes, vous pouvez le faire en ajoutant une nouvelle fonction qui contrôle si le champ s'affiche dans le formulaire de don.

Si vous ajoutez un nouveau champ, vous devrez d'abord créer le champ de don, suivez donc d'abord ces étapes.

Vous pouvez maintenant *masquer* le champ que vous avez enregistré de tous les formulaires de don, sauf celui sur lequel vous souhaitez qu'il apparaisse :

add_filter( 'charitable_donation_form_user_fields', function( $fields, $form ) {

    /* If the field doesn't exist, stop right here. */
    if ( ! array_key_exists( 'my_custom_field', $fields ) ) {
        return $fields;
    }

    /* Match any campaign that DOESN'T have a slug of 'special-campaign' */
    if ( 'special-campaign' !== $form->get_campaign()->post_name ) {    
        unset( $fields['my_custom_field'] );
    }
    
    return $fields;
}, 10, 2 );

Que se passe-t-il ici ?

• Nous voulons que le champ my_custom_field ne s'affiche que sur la campagne dont le slug est « special-campaign ».
• Le champ s'affichera dans toutes les campagnes par défaut, notre code vérifie donc si la campagne n'a *pas* le slug « special-campaign » et le supprime ensuite.

Vous pouvez modifier la condition selon laquelle le champ est affiché. Par exemple, vous pouvez modifier le champ pour qu'il ne s'affiche que pour les campagnes d'une certaine catégorie, ou pour les campagnes qui ont une campagne parente spécifique (c'est-à-dire les collectes de fonds pour l'une de vos campagnes de collecte de fonds peer-to-peer).

Comment modifier un champ de don pour une campagne particulière ?

L'approche utilisée ci-dessus pour afficher un champ sur une campagne particulière peut être adaptée pour *modifier* un champ de don pour une campagne particulière.

Par exemple, si vous ne souhaitez accepter que les dons de donateurs d'un pays spécifique pour une certaine campagne, vous pouvez y parvenir avec le code suivant :

add_filter( 'charitable_donation_form_user_fields', function( $fields, $form ) {
    /* If a country field doesn't exist, stop right here. */
    if ( ! array_key_exists( 'country', $fields ) ) {
        return $fields;
    }

    if ( 'south-africa-only' === $form->get_campaign()->post_name ) {
        $fields['country']['options'] = array(
            'ZA' => 'South Africa',
        );
    }	

    return $fields;

}, 10, 2 );

Ce code fera en sorte que la campagne dont le slug est « south-africa-only » n'affiche que l'Afrique du Sud comme option de pays valide.

Comment faire en sorte qu'un champ de don s'affiche en fonction de la saisie de l'utilisateur ?

Les deux exemples précédents ont montré comment ajouter/modifier des champs de don en fonction de la campagne du formulaire de don. Mais que faire si vous souhaitez afficher ou masquer un champ en fonction de la saisie de l'utilisateur ?

La gestion de cela nécessite une approche différente, utilisant Javascript. Si vous êtes un développeur expérimenté, vous pouvez l'ajouter via un nouveau fichier Javascript, mais dans l'exemple ci-dessous, nous utiliserons la fonction wp_add_inline_script pour ajouter notre Javascript personnalisé sans avoir besoin de créer, d'enregistrer et de mettre en file d'attente un nouveau script.

Dans l'exemple ci-dessous, nous n'affichons notre champ personnalisé, my_custom_field, que lorsque le donateur vient des États-Unis :

add_action( 'wp_enqueue_scripts', function() {
    wp_add_inline_script( 'charitable-script', "
        jQuery('body').on('charitable:form:loaded', (event, donationForm) => {
            var countryField = donationForm.get_input('country');
            function toggleCustomField() {
                donationForm.get_input('my_custom_field').parent().toggle('US' === countryField.val());
            }
            countryField.on('change', toggleCustomField).trigger('change');
        });
    " );
} );

Liste complète des champs de don par défaut

Les champs suivants sont ajoutés par Charitable et ses extensions :

Clé	Description
id_don	L'ID du don
prénom	Le prénom du donateur.
nom	Le nom de famille du donateur.
donateur	Le nom complet du donateur.
email	L'adresse e-mail du donateur.
adresse_donateur	L'adresse complète du donateur, formatée.
adresse	Le premier champ d'adresse du donateur.
adresse_2	Le deuxième champ d'adresse du donateur.
ville	La ville du donateur.
état	L'état du donateur.
code_postal	Le code postal du donateur.
pays	Le pays du donateur.
téléphone	Le numéro de téléphone du donateur.
campagnes	La campagne qui a reçu le don.
liste_catégories_campagnes	Les catégories dans lesquelles la campagne se trouve.
montant_formaté	Le montant du don, formaté selon vos paramètres de devise.
date	La date du don.
heure	L'heure à laquelle le don a été effectué.
statut	Le statut du don. Renvoie la valeur brute de post_status.
libellé_statut	Le statut du don sous forme d'étiquette plus lisible.
passerelle_don	La passerelle de paiement utilisée pour le don.
libellé_passerelle	La passerelle de paiement sous forme de chaîne de caractères conviviale.
clé_don	La clé de don unique.
id_transaction_passerelle	L'identifiant de transaction pour le don dans la passerelle de paiement utilisée (par exemple, PayPal, Stripe).
mode_test	Si le don a été effectué en mode test.
résumé_don	Un résumé lisible du don, indiquant la campagne recevant le don et le montant donné.
consentement_contact	Si le donateur a donné son consentement pour être contacté.
couvrir_frais	Si le donateur a couvert les frais. Ajouté par Fee Relief.
montant_frais	Le montant des frais de traitement payés par le donateur. Ajouté par Fee Relief.
montant_frais_formaté	Le montant des frais de traitement payés par le donateur, formaté selon vos paramètres de devise. Ajouté par Fee Relief.
don_total_avec_frais	Le montant total du don, frais de traitement inclus. Ajouté par Réduction des frais.
don_total_avec_frais_formaté	Le montant total du don, frais de traitement inclus, formaté selon vos paramètres de devise. Ajouté par Réduction des frais.
consentement_suivi	Si le donateur a donné la permission de suivre son activité dans la newsletter (ouvertures, clics). Ceci s'applique uniquement si vous utilisez Campaign Monitor. Ajouté par Connexion Newsletter.
don_anonyme	Si le donateur a choisi de rester anonyme. Ajouté par Dons Anonymes.
commentaire_donateur	Le commentaire laissé par le donateur. Ajouté par Commentaires du Donateur.
giftaid	Si le donateur a demandé l'application du Gift Aid. Ajouté par Gift Aid.
déclaration_giftaid	La déclaration que le donateur a acceptée lorsqu'il a demandé l'application du Gift Aid. Ajouté par Gift Aid.
titre	Le titre du donateur (M., Mme, Mlle, etc.). Ajouté par Gift Aid.
adresse_3	La troisième ligne de l'adresse du donateur. Ajouté par Gift Aid.