AWARE Whistler est une organisation caritative engagée dans la protection de l'environnement naturel de Whistler, Canada. Elle marque cette année son 30e anniversaire en tant qu'organisation et célèbre l'occasion en lançant la campagne de financement 30 for 30 Fundraiser.
L'objectif de la campagne « 30 for 30 Fundraiser » est de collecter 60 000 $, dont 30 000 $ provenant des entreprises et 30 000 $ de dons individuels.
AWARE utilise l'approche de financement axée sur les campagnes de Charitable pour alimenter cette campagne, avec deux campagnes de financement individuelles mises en place : une pour les entreprises et une pour les particuliers.
Le défi
Bien sûr, des campagnes uniques comme celle-ci ont tendance à avoir des besoins uniques, et la campagne « 30 for 30 Fundraiser » ne fait pas exception.
Étant donné que l'une des deux campagnes de financement est spécifiquement axée sur l'obtention de dons d'entreprises, un champ « Nom de l'entreprise » est nécessaire dans le formulaire de don de cette campagne. De plus, lorsque les donateurs sont affichés sur le site (en utilisant le shortcode ou le widget Donateurs), c'est le nom de l'entreprise qui doit être affiché, et non le nom de la personne qui fait le don.
Heureusement, la flexibilité de Charitable est parfaitement adaptée aux besoins d'AWARE. Voyons comment.
Étape 1. Ajouter un champ « Nom de l'entreprise »
La première chose à faire est de créer un nouveau champ de don, en utilisant l'API des champs de don.
Examinons le code requis pour y parvenir :
/**
* STEP 1: Register the "Company Name" Donation Field.
*
* On the `init` hook, we create a new Donation Field. It has a
* key of `company_name` (this is how we will reference it later),
* and it's set up as a required field in the donation form, shown
* after the `last_name` field.
*/
add_action( 'init', function() {
/**
* Add a "Company Name" field.
*/
$field = new Charitable_Donation_Field(
'company_name',
[
'label' => 'Company Name',
'data_type' => 'user',
'donation_form' => [
'show_after' => 'last_name',
'required' => true,
],
'admin_form' => true,
'show_in_meta' => true,
'show_in_export' => true,
'email_tag' => [
'description' => 'The company name',
],
]
);
/**
* Register the field.
*/
charitable()->donation_fields()->register_field( $field );
}, 100 );
Il y a un peu de choses qui se passent ici. Tout d'abord, tout en haut, nous configurons une fonction à exécuter lors du hook init. C'est le meilleur hook à utiliser chaque fois que vous souhaitez enregistrer un nouveau champ de don.
À l'intérieur de notre fonction, nous créons un nouveau champ de don avec l'objet Charitable_Donation_Field. Examinons de plus près ce passage :
$field = new Charitable_Donation_Field(
'company_name',
[
'label' => 'Company Name',
'data_type' => 'user',
'donation_form' => [
'show_after' => 'last_name',
'required' => true,
],
'admin_form' => true,
'show_in_meta' => true,
'show_in_export' => true,
'email_tag' => [
'description' => 'The company name',
],
]
);
Ce que nous faisons ici, c'est créer un champ avec une clé de company_name (nous en aurons besoin plus tard). Nous avons défini une étiquette, l'avons défini comme un champ utilisateur et avons défini quelques règles de base sur la façon dont il doit apparaître dans le formulaire de don : juste après le champ last_name et comme champ obligatoire.
Nous l'avons également configuré pour qu'il s'affiche dans le formulaire de don de l'administrateur, les métadonnées du don et le fichier d'exportation des dons. Nous avons même indiqué à Charitable de créer une balise d'e-mail pour celui-ci, afin que nous puissions l'utiliser dans nos e-mails de reçu de don.
Enfin, nous enregistrons ce champ auprès de l'API des champs de don :
charitable()->donation_fields()->register_field( $field );
Étape 2. Afficher le champ « Nom de l'entreprise » uniquement sur une campagne
Par défaut, lorsque vous configurez un champ de don, il apparaît dans le formulaire de don de chaque campagne. Pour la campagne « 30 for 30 », AWARE souhaite que le champ n'apparaisse que dans le formulaire de don de la campagne des entreprises.
Voici comment nous y parvenons :
/**
* STEP 2: Only show the field on a specific campaign.
*
* We only want the field to show up on a single campaign's
* form, so we *remove* it from all other campaigns' donation
* forms.
*/
add_filter( 'charitable_donation_form_user_fields', function( $fields, Charitable_Donation_Form $form ) {
/**
* Check the campaign ID of the donation form being
* shown. If it isn't the one where we want the field,
* remove the field using the unset() function.
*/
if ( 123 != $form->get_campaign()->ID ) {
unset( $fields['company_name'] );
}
return $fields;
}, 10, 2 );
La façon dont nous résolvons ce problème est de *supprimer* le champ company_name lorsque nous n'affichons *pas* le formulaire de don de la campagne des entreprises. Toute la magie opère ici :
if ( 123 != $form->get_campaign()->ID ) {
unset( $fields['company_name'] );
}
Dans ce cas, nous imaginons que la campagne Business a un ID de 123. Ainsi, lorsque nous examinons les champs d'un formulaire particulier, nous vérifions l'ID de la campagne pour le formulaire, et s'il n'est pas 123, nous utilisons la fonction unset() pour supprimer notre champ, en le référençant par la clé de company_name, que nous avons définie à l'étape 1.
Étape 3. Personnalisez le nom du donateur dans le shortcode ou le widget Donateurs
Maintenant que nous avons ajouté notre champ Nom de l'entreprise, il ne nous reste plus qu'à l'utiliser à la place du prénom et du nom du donateur lors de l'affichage des dons pour la campagne Business.
Voyons le code :
/**
* STEP 3: Use the company name for the donor name.
*
* When showing the donor name for a particular donation,
* check if the donation was to the campaign with our
* Company Name field. If it was, show the Company Name
* instead of the individual's name.
*/
add_filter( 'charitable_donor_loop_donor_name', function( $name, $args ) {
/**
* Get the Donor object from the argument array.
*/
$donor = $args['donor'];
/**
* Check if there is a Donation object associated
* with this Donor.
*/
$donation = $donor->get_donation();
if ( ! $donation ) {
return $name;
}
/**
* Get the campaign that received the donation.
*/
$campaign_id = current( $donation->get_campaign_donations() )->campaign_id;
/**
* If this was a donation to our campaign,
* let's change the donor name.
*/
if ( 123 == $campaign_id ) {
$name = $donation->get( 'company_name' );
}
return $name;
}, 15, 2 );
Tout d'abord, remarquez que ceci est configuré comme une fonction appelée sur le hook charitable_donor_loop_donor_name. Nous utilisons ce hook car il est affiché chaque fois qu'une liste de donateurs est affichée avec le widget Donateurs ou le shortcode.
À l'intérieur de la fonction, nous obtenons d'abord l'objet Charitable_Donor à partir du paramètre $args. Nous obtenons ensuite l'objet Charitable_Donation via la méthode $donor->get_donation() :
/**
* Check if there is a Donation object associated
* with this Donor.
*/
$donation = $donor->get_donation();
if ( ! $donation ) {
return $name;
}
Vous vous demandez peut-être pourquoi nous vérifions si $donation est défini. La raison en est que parfois, Charitable_Donor n'est pas configuré avec un don spécifique. Un tel exemple est lorsque le widget/shortcode Donateurs est configuré pour regrouper plusieurs dons du même donateur en un seul — dans ce cas, aucun objet Charitable_Donation n'est appelé, et nous afficherons simplement le nom du donateur.
Par conséquent, une mise en garde importante de cette approche est qu'elle ne fonctionnera que si le widget/shortcode Donateurs est configuré pour afficher chaque don individuellement, au lieu de regrouper plusieurs dons de la même personne.
Ensuite, nous utilisons l'objet Charitable_Donation pour découvrir à quelle campagne le don a été fait, et vérifions s'il s'agit de notre campagne Business (celle avec l'ID 123) :
/**
* Get the campaign that received the donation.
*/
$campaign_id = current( $donation->get_campaign_donations() )->campaign_id;
/**
* If this was a donation to our campaign,
* let's change the donor name.
*/
if ( 123 == $campaign_id ) {
$name = $donation->get( 'company_name' );
}
La dernière partie de ceci vérifie simplement que $campaign_id est 123. Si c'est le cas, nous obtenons le nom de l'entreprise comme ceci :
$donation->get( 'company_name' );
Notez que company_name correspond à la clé du champ de don que nous avons enregistré à l'étape 1.
Et avec cela, nous avons terminé !
La solution complète
Vous pouvez voir tout le code réuni en un seul endroit dans notre bibliothèque de code Github :
Pour le voir en action – et si vous souhaitez soutenir le travail important accompli par AWARE Whistler – visitez la page 30 for 30 Fundraiser sur leur site web.
Mot de la fin
Si vous avez apprécié ce tutoriel et souhaitez que nous en écrivions un sur un sujet différent, faites-le nous savoir ! Vous pouvez nous contacter par e-mail en remplissant le formulaire sur notre page Support, ou laisser un commentaire ci-dessous.
Laisser un commentaire