Möchten Sie, dass ein benutzerdefiniertes Feld aus Ihrem Spendenformular auf der PDF-Quittung angezeigt wird? Wenn Sie ein benutzerdefiniertes Feld zu einem Legacy-Formular hinzufügen oder eines im visuellen Kampagnen-Builder erstellen, speichert Charitable die Antwort des Spenders mit der Spende – aber die PDF-Quittungsvorlage druckt sie nicht automatisch. Sie müssen der Quittung mitteilen, wo sich der Wert befindet und wie er angezeigt werden soll.

Diese Anleitung führt Sie durch die Schritte, um ein benutzerdefiniertes Spendenfeld zu Ihrer PDF-Quittung hinzuzufügen, unabhängig davon, ob das Feld aus einem Legacy-Formular oder dem visuellen Formular-Builder stammt.

Hinweis: Dieser Abschnitt geht davon aus, dass Sie Charitable Pro 1.8.13+ verwenden und kleine Mengen an PHP involviert sind. Wenn Sie sich nicht wohl dabei fühlen, Code zu bearbeiten, fügen Sie den Ausschnitt in ein Tool wie WPCode ein, damit Sie die Theme-Dateien nicht direkt bearbeiten müssen, oder übergeben Sie ihn an Ihren Entwickler.

Wie werden benutzerdefinierte Felder gespeichert?

Bevor Sie ein Feld auf der Quittung anzeigen können, benötigen Sie zwei Dinge: wo sein Wert gespeichert ist und nach welchem Schlüssel er nachgeschlagen werden kann. Charitable speichert benutzerdefinierte Felder von Legacy-Formularen und visuellen Formularen als Spenden-Post-Meta, aber der Meta-Schlüssel sieht je nachdem, welches Formular ihn erstellt hat, unterschiedlich aus.

Für benutzerdefinierte Felder von Legacy-Formularen ist der Meta-Schlüssel das, was bei der Registrierung des Feldes mit der Donation Fields API registriert wurde. Wenn Sie ein Feld mit dem Schlüssel t_shirt_size registriert haben, wird der Wert unter genau diesem Schlüssel gespeichert.

Für benutzerdefinierte Felder von visuellen Formularen verwendet der Schlüssel das Format field_X, wobei X die numerische ID ist, die der Kampagnen-Builder dem Feld zugewiesen hat. Versteckte Felder sind die Ausnahme – diese verwenden den Namen, den Sie in die Einstellung Feldname eingegeben haben.

Den Meta-Schlüssel für Ihr Feld finden

Der einfachste Weg, um zu bestätigen, welchen Meta-Schlüssel ein Feld verwendet, ist, eine echte Spende zu betrachten, die das Feld enthielt.

Für ein Legacy-Formular ist der Meta-Schlüssel der Array-Schlüssel, den Sie bei der Registrierung des Feldes mit dem Filter charitable_default_donation_fields verwendet haben. Wenn Sie den Ausschnitt nicht selbst geschrieben haben, können Sie Ihre Website durchsuchen (oder Ihren Entwickler fragen), um diesen Filter zu finden und den Schlüssel zu bestätigen.

Für ein visuelles Formular gehen Sie zu Charitable » Spenden, öffnen Sie eine Testspende, die das benutzerdefinierte Feld übermittelt hat, und suchen Sie in den gespeicherten Daten der Spende nach Einträgen wie field_3 oder field_5. Die Zahl ist die Builder-ID des Feldes. Wenn Sie lieber alle Meta-Schlüssel auf einmal sehen möchten, können Sie diesen temporären Ausschnitt auf jeder Admin-Seite einfügen:

echo '<pre>';
print_r( get_post_meta( 123 ) ); // Replace 123 with your test donation ID.
echo '</pre>';

Hinweis: Sobald Sie die benötigten Schlüssel notiert haben, entfernen Sie den Ausschnitt – das Belassen von print_r()-Aufrufen in der Produktionsausgabe ist unordentlich und kann Spenderdaten preisgeben.

Hinzufügen eines Feldes mit einem Hook (empfohlen)

Charitable löst eine Aktion namens charitable_pdf_receipt_after_donor_details direkt nach dem Spenderdetails-Block auf jeder PDF-Spendenquittung aus. Das Einhaken in diese Aktion ist der einfachste Weg, ein benutzerdefiniertes Feld hinzuzufügen, da Sie keine Vorlagendateien überschreiben müssen – Ihre Änderungen überleben Plugin-Updates ohne zusätzliche Arbeit.

Um den Snippet zu aktivieren, fügen Sie ihn in die functions.php Datei Ihres Child-Themes oder in ein Code-Snippets-Plugin ein:

add_action( 'charitable_pdf_receipt_after_donor_details', function( $donor, $donation ) {

    // Replace 't_shirt_size' with your field's meta key.
    // For a visual form custom field, this will look like 'field_3'.
    $value = get_post_meta( $donation->ID, 't_shirt_size', true );

    if ( empty( $value ) ) {
        return;
    }

    printf(
        '<p style="margin-top: 10px; margin-bottom: 0;"><strong>%s:</strong> %s</p>',
        esc_html__( 'T-Shirt Size', 'charitable-pro' ),
        esc_html( $value )
    );

}, 10, 2 );

Das Beispiel druckt das Feld unter dem Namen, der Adresse und der E-Mail-Adresse des Spenders. Tauschen Sie beim Anpassen den Meta-Schlüssel, das sichtbare Label und das Markup aus, um das Feld abzugleichen, das Sie hinzufügen.

Hinweis: Wenn Ihr Wert HTML enthält – zum Beispiel die Ausgabe eines Langtextfeldes – verwenden Sie wp_kses_post() anstelle von esc_html(), damit grundlegende Formatierungs-Tags erhalten bleiben.

Hinzufügen eines Feldes durch Überschreiben der Vorlage

Wenn Sie das Feld an einer anderen Stelle als nach den Spenderdetails platzieren müssen – zum Beispiel innerhalb der Spendentabelle oder in der Fußzeile – können Sie die PDF-Spendenquittungsvorlage überschreiben.

Die PDF-Vorlagen von Charitable können per Theme überschrieben werden. Um das Hauptlayout der PDF-Datei anzupassen, kopieren Sie diese Datei:

wp-content/plugins/charitable-pro/templates/pro/pdf-receipts/pdf.php

In Ihr aktives Theme unter diesem Pfad:

wp-content/themes/your-theme/charitable-pro/pro/pdf-receipts/pdf.php

Sobald Ihre Kopie vorhanden ist, wird Charitable sie anstelle der Plugin-Version laden. Das gleiche Pfadmuster funktioniert für die beiden Teilvorlagen, die pdf.php aufruft:

• Spenderdetails: templates/pro/pdf-receipts/donation-receipt/donor-details.php
• Spendendetails: templates/pro/pdf-receipts/donation-receipt/details.php

Innerhalb jeder kopierten Vorlage ist die Variable $donation das vollständige Charitable_Donation Objekt. Um den Wert eines benutzerdefinierten Feldes abzurufen, verwenden Sie denselben get_post_meta() Aufruf aus der vorherigen Methode und fügen Sie dann Markup hinzu, wo immer der Wert erscheinen soll:

<?php
$value = get_post_meta( $donation->ID, 'field_3', true );
if ( ! empty( $value ) ) :
    ?>
    <p><strong><?php esc_html_e( 'Gift Aid Eligible', 'charitable-pro' ); ?>:</strong> <?php echo esc_html( $value ); ?></p>
    <?php
endif;
?>

Hinweis: Vorlagenüberschreibungen müssen bei jedem Update von Charitable Pro überprüft werden. Wenn die Plugin-Version der Vorlage neue Funktionen oder Fehlerbehebungen erhält, wird Ihre Überschreibung diese nicht automatisch sehen. Die oben genannte Hook-Methode vermeidet dies vollständig, verwenden Sie also eine Vorlagenüberschreibung nur, wenn Sie die Platzierung kontrollieren müssen.

Vorschau Ihrer Änderungen

Sobald Ihr Snippet oder Ihre Vorlagenüberschreibung gespeichert ist, generieren Sie eine echte PDF-Datei, um zu bestätigen, dass das Feld wie erwartet angezeigt wird. Wählen Sie auf dem Bildschirm Charitable » Spenden eine Spende aus, die das benutzerdefinierte Feld enthielt, und klicken Sie dann auf das PDF-Symbol daneben, um die Quittung herunterzuladen. Wenn das Feld nicht angezeigt wird, gehen Sie diese Prüfungen nacheinander durch:

• Stellen Sie sicher, dass der Meta-Schlüssel exakt übereinstimmt – field_3 und field_03 sind nicht dasselbe.
• Überprüfen Sie, ob die getestete Spende tatsächlich einen Wert für das Feld übermittelt hat. Leere Werte werden nicht gedruckt.
• Versuchen Sie eine andere Testspende, um auszuschließen, dass ein Eintrag leer ist.

Hinweis: Felder, die auf dem Spenden-Admin-Bildschirm leer erscheinen, werden auch im PDF-Format leer sein. Die Quittung kann keine Daten anzeigen, die die Spende nie gesammelt hat.