AWARE Whistler is a charity committed to protecting the natural environment of Whistler, Canada. It marks its 30th anniversary as an organisation this year and is celebrating the occasion by launching the 30 for 30 Fundraiser.
The goal of the 30 for 30 Fundraiser is to raise $60,000, with $30,000 raised from businesses and $30,000 raised from individual donations.
AWARE are using Charitable’s campaign-driven fundraising approach to power this campaign, with two individual fundraising campaigns set up: one for businesses, and one for individuals.
The challenge
Of course, unique campaigns like this tend to have unique needs, and the 30 for 30 Fundraiser is no exception.
Since one of the two fundraising campaigns is specifically focused on getting donations from businesses, a Company Name field is needed in that campaign’s donation form. Also, when donors are shown on the site (using the Donors shortcode or widget), it’s the company’s name that should be shown — not the name of the person donating.
Thankfully, Charitable’s flexibility is ideally suited for AWARE’s needs. Let’s see how.
Step 1. Add a “Company Name” field
The first thing we need to do is to create a new donation field, using the Donation Fields API.
Let’s look at the code required to achieve that:
/**
* 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 );
There’s a bit going on here. First of all, right at the top, we are setting up a function to be run on the init hook. This is the best hook to use any time you want to register a new donation field.
Inside of our function, we create a new Donation Field with the Charitable_Donation_Field object. Let’s take a closer look at that bit:
$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',
],
]
);
What we’re doing here is creating a field with a key of company_name (we’ll need this later on). We have set a label, defined it as a user field, and set up some basic rules for how it should appear in the donation form: right after the last_name field and as a required field.
We’ve also set it up to show in the admin donation form, the donation meta and donations export file. We even told Charitable to create an email tag for it, so we can use it in our donation receipt emails.
Finally, we register this field with the Donation Fields API:
charitable()->donation_fields()->register_field( $field );
Step 2. Only show the “Company Name” field on one campaign
By default, when you set up a donation field, it will show up in every campaign’s donation form. For the “30 for 30” campaign though, AWARE only want the field to appear in the donation form of the Business fundraiser.
Here’s how we achieve that:
/**
* 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 );
The way we solve this problem is by removing the company_name field when we are not showing the Business campaign’s donation form. All the magic happens rights here:
if ( 123 != $form->get_campaign()->ID ) {
unset( $fields['company_name'] );
}
In this case, we’re imaging that the Business campaign has an ID of 123. So when we’re looking at the fields in a particular form, we check the ID of the campaign for the form, and if it isn’t 123, we use the unset() function to get rid of our field, referencing to it by the key of company_name, which we set in Step 1.
Step 3. Customise the donor name in the Donors shortcode or widget
Now that we’ve added our Company Name field, all that’s left is for us to use that instead of the donor’s first and last name when showing donations to the Businesses campaign.
Let’s see the 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 );
First of all, notice that this is set up as a function called on the charitable_donor_loop_donor_name hook. We use this hook since it is shown whenever a list of donors is shown with the Donors widget or shortcode.
Inside the function, we first get the Charitable_Donor object from the $args parameter. We then get the Charitable_Donation object through the $donor->get_donation() method:
/**
* Check if there is a Donation object associated
* with this Donor.
*/
$donation = $donor->get_donation();
if ( ! $donation ) {
return $name;
}
You may wonder why we check whether $donation is set. The reason for this is because sometimes, Charitable_Donor is not set up with a specific donation. One such example is when the Donors widget/shortcode is set up to group multiple donations by the same donor into one — in that case, no Charitable_Donation object is called up, and we will just show the donor’s name.
Therefore, an important caveat of this approach is that this will only work if the Donors widget/shortcode is set up to show each donation individually, instead of grouping multiple donations by the same person.
Moving on, we use the Charitable_Donation object to find out which campaign was donated to, and check if it’s our Business campaign (the one with an ID of 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' );
}
The last part of this simply checks that the $campaign_id is 123. If it is, we get the company name like this:
$donation->get( 'company_name' );
Note that company_name matches the key of the donation field we registered back in step 1.
And with that, we’re all done!
The complete solution
You can see all the code put together in one place in our Github code library:
To see it in action – and if you would like to show your support for the important work done by AWARE Whistler – visit the 30 for 30 Fundraiser page on their website.
Final word
If you enjoyed this tutorial and would like to see us write one about a different topic, let us know! You can reach us via email by filling out the form over at our Support page, or leave a comment below.
Leave a Reply