Die Donation Fields API bietet eine leistungsstarke und flexible Möglichkeit, Ihre Spendenfelder hinzuzufügen, zu entfernen und zu bearbeiten.

• Was sind Spendenfelder?
• Wie erhalte ich den Wert für ein bestimmtes Feld?
• Wie füge ich meinem Spendenformular ein neues Feld hinzu?
• Wie ändere ich ein vorhandenes Spendenfeld?
• Wie füge ich einer bestimmten Kampagne ein Spendenfeld hinzu?
• Wie ändere ich ein Spendenfeld für eine bestimmte Kampagne?
• Wie lasse ich ein Feld bedingt anzeigen?
• Vollständige Liste der Standard-Spendenfelder

Was sind Spendenfelder?

Spendenfelder sind alle Informationen über eine Spende, die Ihnen zur Verfügung stehen. Hier sind zum Beispiel einige der standardmäßig verfügbaren Felder:

• first_name – Erhalten Sie den Vornamen des Spenders.
• last_name – Erhalten Sie den Nachnamen des Spenders.
• amount_formatted – Erhalten Sie den Spendenbetrag, formatiert gemäß den Währungseinstellungen Ihrer Website (z. B. 50,00 $).
• date – Das Datum, an dem die Spende getätigt wurde.
• gateway_label – Die vom Spender verwendete Zahlungsmethode.

Wie erhalte ich den Wert für ein bestimmtes Spendenfeld?

Sie können den Wert eines beliebigen Spendenfeldes über das Charitable_Donation-Objekt der Spende abrufen.

Der erste Schritt ist, ein Charitable_Donation-Objekt zu erhalten:

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

Als Nächstes können Sie den Feldwert abrufen, indem Sie get() auf dem Objekt aufrufen, wie Sie in den folgenden Beispielen sehen können:

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

Um alles zusammenzufügen:

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

Wie füge ich meinem Spendenformular ein neues Feld hinzu?

Das Hinzufügen eines neuen Feldes ist ein zweistufiger Prozess.

Zuerst erstellen Sie ein neues Charitable_Donation_Field-Objekt, das die Parameter Ihres Feldes definiert: seine Bezeichnung, den Datentyp, wie es im Spendenformular (falls überhaupt) enthalten sein soll, ob es zur Spendenexportdatei hinzugefügt werden soll und mehr.

Als Nächstes fügen Sie dieses Feld zur Klasse Charitable_Donation_Field_Registry hinzu, die eine Möglichkeit bietet, Spendenfelder zu speichern und abzurufen.

Sehen wir uns an, wie das in einem Beispiel funktioniert:

/**
 * 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 );
} );

Im obigen Beispiel haben wir ein neues Feld mit dem Schlüssel my_custom_field erstellt. Hier sind seine definierten Parameter:

• Seine Bezeichnung ist „Mein benutzerdefiniertes Feld“. Dies wird im Spendenformular, im Bereich der Spenden-Admin-Details und im Spendenexport als Spaltenüberschrift verwendet.
• Sein Datentyp ist meta. Das bedeutet, dass es als Metafeld speziell für diese Spende gespeichert wird.
• Es ist so eingerichtet, dass es im Spendenformular direkt nach dem phone-Feld angezeigt wird. Es ist ein optionales Feld.
• Es wird auch dem Admin-Spendenformular hinzugefügt.
• Wenn Sie die Details einer Spende anzeigen, können Sie im Abschnitt „Spenden-Details“ sehen, was der Spender für dieses Feld eingegeben hat.
• Wenn Sie einen Spendenexport herunterladen, wird eine neue Spalte „Mein benutzerdefiniertes Feld“ hinzugefügt, die anzeigt, was Spender für dieses Feld eingegeben haben.
• Für dieses Feld wurde ein neuer E-Mail-Tag erstellt, sodass Sie ihn einfach in spendenspezifische E-Mails aufnehmen können, wie z. B. die Spendenquittung (für Spender) oder die Spendenbenachrichtigung (für Administratoren).

Dies ist ein relativ einfaches Beispiel, aber es leistet viel. Klicken Sie hier für eine detailliertere Aufschlüsselung aller verfügbaren Parameter bei der Erstellung von Charitable_Donation_Field Objekten.

Wie ändere ich ein vorhandenes Spendenfeld?

Um ein vorhandenes Spendenfeld zu ändern, rufen Sie zuerst das Feld aus der Charitable_Donation_Field_Registry ab und aktualisieren dann den Feldwert.

Um den Feldwert zu aktualisieren, können wir set() für das Feld aufrufen oder den magischen Setter verwenden.

/**
 * 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';
} );

Weitere Informationen zur Aktualisierung von Feldargumenten finden Sie in der detaillierten Referenz für diese Klassenmethoden:

• Charitable_Donation_Field::set()
• Charitable_Donation_Field::__set() (magischer Setter).

Wie füge ich ein Feld zu dem Spendenformular einer bestimmten Kampagne hinzu?

Wenn ein neues oder vorhandenes Feld nur für bestimmte Kampagnen angezeigt werden soll, können Sie dies tun, indem Sie eine neue Funktion hinzufügen, die steuert, ob das Feld im Spendenformular angezeigt wird.

Wenn Sie ein neues Feld hinzufügen, müssen Sie zuerst das Spendenfeld erstellen. Befolgen Sie also zuerst diese Schritte.

Jetzt können Sie das registrierte Feld von allen Spendenformularen ausblenden, außer von dem, auf dem es angezeigt werden soll:

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 );

Was passiert hier?

• Wir möchten, dass das Feld my_custom_field nur für die Kampagne mit dem Slug „special-campaign“ angezeigt wird.
• Das Feld wird standardmäßig in allen Kampagnen angezeigt. Daher prüft unser Code, ob die Kampagne nicht den Slug „special-campaign“ hat, und entfernt es dann.

Sie können die Bedingung ändern, unter der das Feld angezeigt wird. Sie können das Feld beispielsweise so ändern, dass es nur für Kampagnen einer bestimmten Kategorie oder für Kampagnen mit einer bestimmten übergeordneten Kampagne angezeigt wird (d. h. Spendenaktionen für eine Ihrer Peer-to-Peer-Spendenaktionen).

Wie ändere ich ein Spendenfeld für eine bestimmte Kampagne?

Der oben verwendete Ansatz, um ein Feld für eine bestimmte Kampagne anzuzeigen, kann angepasst werden, um ein Spendenfeld für eine bestimmte Kampagne zu ändern.

Wenn Sie beispielsweise für eine bestimmte Kampagne nur Spenden von Spendern aus einem bestimmten Land akzeptieren möchten, können Sie dies mit dem folgenden Code erreichen:

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 );

Dieser Code bewirkt, dass für die Kampagne mit dem Slug „south-africa-only“ nur Südafrika als gültige Länderoption angezeigt wird.

Wie lasse ich ein Spendenfeld basierend auf Benutzereingaben anzeigen?

Die beiden vorherigen Beispiele zeigten, wie Spendenfelder basierend auf der Kampagne des Spendenformulars hinzugefügt/geändert werden. Aber was ist, wenn Sie ein Feld basierend auf Benutzereingaben anzeigen oder ausblenden möchten?

Die Handhabung erfordert einen anderen Ansatz mit Javascript. Wenn Sie ein erfahrener Entwickler sind, können Sie dies über eine neue Javascript-Datei hinzufügen. Im folgenden Beispiel verwenden wir jedoch die Funktion wp_add_inline_script, um unser benutzerdefiniertes Javascript hinzuzufügen, ohne ein neues Skript erstellen, registrieren und einreihen zu müssen.

Im folgenden Beispiel zeigen wir unser benutzerdefiniertes Feld my_custom_field nur an, wenn der Spender aus den Vereinigten Staaten stammt:

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');
        });
    " );
} );

Vollständige Liste der Standard-Spendenfelder

Die folgenden Felder werden von Charitable und seinen Erweiterungen hinzugefügt:

Schlüssel	Beschreibung
donation_id	Die Spenden-ID
vorname	Der Vorname des Spenders.
nachname	Der Nachname des Spenders.
spender	Der vollständige Name des Spenders.
E-Mail	Die E-Mail-Adresse des Spenders.
spender_adresse	Die vollständige Adresse des Spenders, formatiert.
Adresse	Das erste Adressfeld des Spenders.
adresse_2	Das zweite Adressfeld des Spenders.
Stadt	Die Stadt des Spenders.
Bundesland	Der Bundesstaat des Spenders.
Postleitzahl	Die Postleitzahl des Spenders.
Land	Das Land des Spenders.
Telefon	Die Telefonnummer des Spenders.
kampagnen	Die Kampagne, die die Spende erhalten hat.
kampagnen_kategorien_liste	Die Kategorien, in denen sich die Kampagne befindet.
betrag_formatiert	Der Spendenbetrag, formatiert gemäß Ihren Währungseinstellungen.
Datum	Das Datum der Spende.
zeit	Die Uhrzeit, zu der die Spende getätigt wurde.
Status	Der Spendenstatus. Gibt den Rohwert von post_status zurück.
Statusbezeichnung	Der Spendenstatus als besser lesbare Bezeichnung.
Spendenzahlungstor	Das für die Spende verwendete Zahlungs-Gateway.
Zahlungstorbezeichnung	Das Zahlungs-Gateway als lesbare Zeichenfolge.
Spendenschlüssel	Der eindeutige Spenden-Schlüssel.
Zahlungstransaktions-ID	Die Transaktions-ID für die Spende im verwendeten Zahlungs-Gateway (z. B. PayPal, Stripe).
Testmodus	Ob die Spende im Testmodus erfolgte.
Spendenzusammenfassung	Eine lesbare Zusammenfassung der Spende, die die Kampagne, die die Spende erhält & den gespendeten Betrag auflistet.
Kontaktzustimmung	Ob der Spender seine Zustimmung zur Kontaktaufnahme gegeben hat.
Gebühren übernehmen	Ob der Spender die Gebühren übernommen hat. Hinzugefügt von Gebührenentlastung.
Gebührenbetrag	Der vom Spender gezahlte Betrag für die Bearbeitungsgebühren. Hinzugefügt von Gebührenentlastung.
Gebührenbetrag formatiert	Der vom Spender gezahlte Betrag für die Bearbeitungsgebühren, formatiert gemäß Ihren Währungseinstellungen. Hinzugefügt von Gebührenentlastung.
Gesamtspende mit Gebühren	Der Gesamtspendenbetrag einschließlich der Bearbeitungsgebühren. Hinzugefügt von Gebührenentlastung.
Gesamtspende mit Gebühren formatiert	Der Gesamtspendenbetrag einschließlich der Bearbeitungsgebühren, formatiert gemäß Ihren Währungseinstellungen. Hinzugefügt von Gebührenentlastung.
Zustimmung zur Nachverfolgung	Ob der Spender die Erlaubnis erteilt hat, seine Newsletter-Aktivitäten (Öffnungen, Klicks) zu verfolgen. Dies gilt nur, wenn Sie Campaign Monitor verwenden. Hinzugefügt von Newsletter Connect.
Anonyme Spende	Ob der Spender sich entschieden hat, anonym zu bleiben. Hinzugefügt von Anonyme Spenden.
Kommentar des Spenders	Der vom Spender hinterlassene Kommentar. Hinzugefügt von Spenderkommentare.
Geschenk-Hilfe	Ob der Spender die Geschenkeinnahmen beansprucht hat. Hinzugefügt von Geschenkeinnahmen.
Geschenk-Hilfe-Erklärung	Die Erklärung, der der Spender zugestimmt hat, als er die Geschenkeinnahmen beansprucht hat. Hinzugefügt von Geschenkeinnahmen.
Titel	Der Titel des Spenders (Herr, Frau, Frl., usw.). Hinzugefügt von Geschenkeinnahmen.
Adresse Zeile 3	Die dritte Zeile in der Adresse des Spenders. Hinzugefügt von Geschenkeinnahmen.