AWARE Whistler ist eine Wohltätigkeitsorganisation, die sich dem Schutz der natürlichen Umwelt von Whistler, Kanada, verschrieben hat. Sie feiert in diesem Jahr ihr 30-jähriges Bestehen und begeht diesen Anlass mit der Einführung der 30 for 30 Fundraiser.
Das Ziel der 30 for 30 Fundraiser ist es, 60.000 US-Dollar zu sammeln, wobei 30.000 US-Dollar von Unternehmen und 30.000 US-Dollar von Einzelspenden stammen sollen.
AWARE nutzt den kampagnengetriebenen Fundraising-Ansatz von Charitable, um diese Kampagne zu unterstützen. Es wurden zwei individuelle Spendenkampagnen eingerichtet: eine für Unternehmen und eine für Einzelpersonen.
Die Herausforderung
Natürlich haben einzigartige Kampagnen wie diese oft einzigartige Anforderungen, und die 30 for 30 Fundraiser bildet da keine Ausnahme.
Da eine der beiden Spendenkampagnen speziell darauf ausgerichtet ist, Spenden von Unternehmen zu erhalten, wird in deren Spendenformular ein Feld für den Firmennamen benötigt. Außerdem sollte auf der Website (über den Spender-Shortcode oder das Widget) der Firmenname angezeigt werden – nicht der Name der spendenden Person.
Glücklicherweise ist die Flexibilität von Charitable ideal für die Bedürfnisse von AWARE geeignet. Sehen wir uns an, wie.
Schritt 1. Ein Feld „Firmenname“ hinzufügen
Als Erstes müssen wir ein neues Spendenfeld mit der Donation Fields API erstellen.
Werfen wir einen Blick auf den dafür erforderlichen Code:
/**
* 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 );
Hier passiert einiges. Zunächst richten wir ganz oben eine Funktion ein, die beim init Hook ausgeführt wird. Dies ist der beste Hook, wenn Sie ein neues Spendenfeld registrieren möchten.
Innerhalb unserer Funktion erstellen wir ein neues Spendenfeld mit dem Objekt Charitable_Donation_Field. Schauen wir uns diesen Teil genauer an:
$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',
],
]
);
Hier erstellen wir ein Feld mit dem Schlüssel company_name (den wir später benötigen werden). Wir haben eine Beschriftung festgelegt, es als Benutzerfeld definiert und einige grundlegende Regeln für seine Anzeige im Spendenformular festgelegt: direkt nach dem Feld last_name und als Pflichtfeld.
Wir haben es auch so eingerichtet, dass es im Spendenformular des Administrators, in den Spendenmetadaten und in der Exportdatei für Spenden angezeigt wird. Wir haben Charitable sogar angewiesen, ein E-Mail-Tag dafür zu erstellen, damit wir es in unseren Spendenquittungs-E-Mails verwenden können.
Schließlich registrieren wir dieses Feld bei der Donation Fields API:
charitable()->donation_fields()->register_field( $field );
Schritt 2. Das Feld „Firmenname“ nur für eine Kampagne anzeigen
Standardmäßig wird ein Spendenfeld in jedem Spendenformular angezeigt. Für die „30 for 30“-Kampagne möchte AWARE jedoch, dass das Feld nur im Spendenformular der Business-Spendenaktion erscheint.
So erreichen wir das:
/**
* 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 );
Wir lösen dieses Problem, indem wir das Feld company_name *entfernen*, wenn wir *nicht* das Spendenformular der Business-Kampagne anzeigen. Die ganze Magie geschieht hier:
if ( 123 != $form->get_campaign()->ID ) {
unset( $fields['company_name'] );
}
In diesem Fall stellen wir uns vor, dass die Kampagne „Business“ die ID 123 hat. Wenn wir uns also die Felder in einem bestimmten Formular ansehen, überprüfen wir die ID der Kampagne für das Formular. Wenn diese nicht 123 ist, verwenden wir die Funktion unset(), um unser Feld zu entfernen, und beziehen uns dabei auf den Schlüssel company_name, den wir in Schritt 1 festgelegt haben.
Schritt 3. Passen Sie den Spendernamen im Shortcode oder Widget für Spender an
Nachdem wir unser Feld „Firmenname“ hinzugefügt haben, müssen wir nur noch dieses anstelle des Vor- und Nachnamens des Spenders verwenden, wenn Spenden für die Kampagne „Business“ angezeigt werden.
Sehen wir uns den Code an:
/**
* 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 );
Beachten Sie zunächst, dass dies als Funktion eingerichtet ist, die auf dem Hook charitable_donor_loop_donor_name aufgerufen wird. Wir verwenden diesen Hook, da er immer dann angezeigt wird, wenn eine Liste von Spendern mit dem Spender-Widget oder Shortcode angezeigt wird.
Innerhalb der Funktion rufen wir zunächst das Charitable_Donor-Objekt aus dem Parameter $args ab. Anschließend rufen wir das Charitable_Donation-Objekt über die Methode $donor->get_donation() ab:
/**
* Check if there is a Donation object associated
* with this Donor.
*/
$donation = $donor->get_donation();
if ( ! $donation ) {
return $name;
}
Sie fragen sich vielleicht, warum wir prüfen, ob $donation gesetzt ist. Der Grund dafür ist, dass manchmal Charitable_Donor nicht mit einer bestimmten Spende eingerichtet ist. Ein solches Beispiel ist, wenn das Spender-Widget/Shortcode so eingerichtet ist, dass mehrere Spenden desselben Spenders zu einer zusammengefasst werden – in diesem Fall wird kein Charitable_Donation-Objekt aufgerufen, und wir zeigen einfach den Namen des Spenders an.
Daher ist ein wichtiger Hinweis zu diesem Ansatz, dass dies nur funktioniert, wenn das Spender-Widget/Shortcode so eingerichtet ist, dass jede Spende einzeln angezeigt wird, anstatt mehrere Spenden derselben Person zu gruppieren.
Weiter geht es damit, dass wir das Charitable_Donation-Objekt verwenden, um herauszufinden, für welche Kampagne gespendet wurde, und prüfen, ob es sich um unsere Business-Kampagne handelt (die mit der 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' );
}
Der letzte Teil davon prüft einfach, ob $campaign_id 123 ist. Wenn ja, erhalten wir den Firmennamen wie folgt:
$donation->get( 'company_name' );
Beachten Sie, dass company_name mit dem Schlüssel des Spendenfeldes übereinstimmt, das wir in Schritt 1 registriert haben.
Und damit sind wir fertig!
Die vollständige Lösung
Sie können den gesamten Code an einem Ort in unserer Github-Codebibliothek sehen:
Um es in Aktion zu sehen – und wenn Sie die wichtige Arbeit von AWARE Whistler unterstützen möchten – besuchen Sie die Seite 30 for 30 Fundraiser auf deren Website.
Schlusswort
Wenn Ihnen dieses Tutorial gefallen hat und Sie möchten, dass wir eines zu einem anderen Thema schreiben, lassen Sie es uns wissen! Sie können uns per E-Mail erreichen, indem Sie das Formular auf unserer Support-Seite ausfüllen, oder hinterlassen Sie einen Kommentar unten.
Hinterlassen Sie eine Antwort