Wie die automatische Erkennung von Quittungsseiten funktioniert

(Hinweis: Dies gilt für Charitable Pro 1.8.10.5+).

Wenn die Einstellung „Spendenquittungsseite“ in den Charitable-Einstellungen auf „Automatisch“ gesetzt ist, erstellt und verwaltet das Plugin automatisch Quittungsseiten für Ihre Spenden. Dieses System funktioniert nahtlos mit den meisten WordPress-Themes, einschließlich traditioneller (klassischer) Themes und moderner Block-Themes.

Im Automatikmodus verwendet Charitable WordPress-Rewrite-Regeln, um benutzerdefinierte URLs wie /donation-receipt/1234/ zu erstellen, die den Quittungsinhalt anzeigen, ohne dass Sie eine physische Seite erstellen müssen. Das Plugin kümmert sich im Hintergrund um alle technischen Details.

Themes, die mit dem Automatikmodus funktionieren

Zum Zeitpunkt der Erstellung (Version 1.8.10.5) wurden die folgenden Themes getestet und funktionieren korrekt mit der automatischen Erkennung von Quittungsseiten:

Block-Themes (Full Site Editing)

• Twenty Twenty-Three – Standard-Block-Theme von WordPress
• Twenty Twenty-Four – Standard-Block-Theme von WordPress
• Twenty Twenty-Five – Standard-Block-Theme von WordPress

Klassische Themes (traditionelle PHP-Vorlagen)

• Astra – Beliebtes Mehrzweck-Theme
• GeneratePress – Leichtgewichtiges Theme
• OceanWP – Mehrzweck-Theme

Diese Themes funktionieren, da sie die Standard-Template-Hierarchie und Inhaltsfilter von WordPress korrekt unterstützen, wodurch Charitable den Quittungsinhalt zur richtigen Zeit im Seiten-Rendering-Prozess einfügen kann.

Themes, die eine Fallback-Seitenerstellung erfordern

Einige Themes verfügen über einzigartige Rendering-Systeme, die die automatische Erkennung von Quittungsseiten verhindern. Wenn Charitable dieses Problem erkennt, erstellt es automatisch eine Fallback-Seite, um sicherzustellen, dass Quittungen weiterhin korrekt angezeigt werden.

Twenty Twenty-Two ist ein Block-Theme, das einen anderen Ansatz für das Template-Rendering verwendet als spätere Standard-Themes von WordPress. Wenn Charitable versucht, eine Quittungsseite anzuzeigen, erkennt das Template-System des Themes den benutzerdefinierten Quittungs-Endpunkt nicht richtig, was zu einer leeren Seite führt.

Warum es Fallback benötigt: Das Block-Template-System des Themes verarbeitet benutzerdefinierte Endpunkte nicht korrekt, wodurch der Quittungsinhalt nicht gerendert wird. Charitable erkennt dies und erstellt automatisch eine physische WordPress-Seite mit dem [donation_receipt] Shortcode, die das Theme dann korrekt anzeigen kann.

Weitere dokumentierte Beispiele zum Zeitpunkt der Erstellung sind YITH Wonder. YITH Wonder ist ein Premium-Theme mit Fokus auf WooCommerce und einem benutzerdefinierten Page-Builder-System. Ähnlich wie Twenty Twenty-Two hat es Rendering-Eigenheiten, die die automatische Quittungserkennung verhindern.

Hinweis: Wenn Charitable eine Fallback-Seite erstellt, aktualisiert es automatisch Ihre Einstellungen, um diese Seite zu verwenden. Wenn Sie später zu einem anderen Theme wechseln, stellt Charitable die Einstellung „Automatisch“ wieder her, wenn das neue Theme mit dem Automatikmodus funktioniert.

Entwicklerfilter

Charitable bietet mehrere Filter, mit denen Entwickler das Verhalten der Fallback-Seite anpassen können. Alle Filter sind unten mit ihren Standardwerten und Anwendungsfällen dokumentiert.

charitable_receipt_fallback_enabled

Standard: wahr

Zweck: Aktiviert oder deaktiviert das gesamte System zur Erstellung von Fallback-Seiten.

Wann zu verwenden: Wenn Sie die automatische Erstellung von Fallback-Seiten vollständig deaktivieren möchten, z. B. weil Sie die Belegseiten über eine benutzerdefinierte Lösung verwalten.

// Disable fallback page creation
add_filter( 'charitable_receipt_fallback_enabled', '__return_false' );

charitable_receipt_fallback_should_activate

Standard: wahr

Parameter:

• $should_activate (bool) – Ob der Fallback aktiviert werden soll
• $current_setting (string) – Aktuelle Einstellung der Belegseite („auto“ oder Seiten-ID)

Zweck: Steuert, ob das Fallback-System aktiviert werden soll, wenn eine leere Seite erkannt wird. Dies gibt Ihnen eine detaillierte Kontrolle darüber, wann Fallback-Seiten erstellt werden.

Wann zu verwenden: Wenn Sie die Erstellung von Fallbacks unter bestimmten Umständen verhindern möchten, z. B. während der Entwicklung oder für bestimmte Benutzerrollen.

// Only activate fallback for specific themes
add_filter( 'charitable_receipt_fallback_should_activate', function( $should_activate, $current_setting ) {
    $current_theme = get_stylesheet();
    // Only allow fallback for specific problematic themes
    if ( ! in_array( $current_theme, array( 'twentytwentytwo', 'yith-wonder' ) ) ) {
        return false;
    }
    return $should_activate;
}, 10, 2 );

charitable_receipt_fallback_page_slug

Standard: 'donation-receipt-page'

Zweck: Passt den URL-Slug für die Fallback-Seite an, die erstellt wird.

Wann zu verwenden: Wenn die Fallback-Seite eine andere URL-Struktur haben soll oder wenn Sie die URL-Namenskonventionen Ihrer Website anpassen müssen.

// Use a custom slug for the fallback page
add_filter( 'charitable_receipt_fallback_page_slug', function( $slug ) {
    return 'receipt';
} );

charitable_receipt_fallback_page_args

Standard:

array(
    'post_title'   => __( 'Donation Receipt', 'charitable-pro' ),
    'post_content' => '[donation_receipt]',
    'post_status'  => 'publish',
    'post_type'    => 'page',
    'post_name'    => $page_slug, // Set automatically
)

Zweck: Passt die Eigenschaften der Fallback-Seite an, wenn sie erstellt wird. Dazu gehören der Seiten-Titel, der Inhalt, der Status und andere WordPress-Post-Eigenschaften.

Wann zu verwenden: Wenn Sie den Seiten-Titel anpassen, benutzerdefinierten Inhalt vor/nach dem Shortcode hinzufügen, eine bestimmte Seiten-Vorlage festlegen oder andere Seiten-Eigenschaften ändern möchten.

// Customize the fallback page
add_filter( 'charitable_receipt_fallback_page_args', function( $args ) {
    // Change the page title
    $args['post_title'] = 'Your Donation Receipt';
    
    // Add content before the shortcode
    $args['post_content'] = '<p>Thank you for your donation!</p>' . "\n" . '[donation_receipt]';
    
    // Set a custom page template (if your theme supports it)
    // $args['page_template'] = 'custom-receipt-template.php';
    
    return $args;
} );

charitable_receipt_fallback_delete_on_theme_switch

Standard: false

Zweck: Steuert, ob die Fallback-Seite automatisch gelöscht werden soll, wenn Sie von einem problematischen Theme wegwechseln.

Wann zu verwenden: Wenn Sie Fallback-Seiten automatisch bereinigen möchten, wenn sie nicht mehr benötigt werden. Standardmäßig bleiben die Seiten erhalten (aber die Einstellungen werden auf „Automatisch“ zurückgesetzt), sodass Sie sie manuell überprüfen oder löschen können.

// Automatically delete fallback page on theme switch
add_filter( 'charitable_receipt_fallback_delete_on_theme_switch', '__return_true' );

Fehlerbehebung

Wenn Sie Probleme mit Belegseiten beheben müssen, können Sie eine detaillierte Protokollierung aktivieren, indem Sie Folgendes zu Ihrer wp-config.php-Datei hinzufügen:

define( 'CHARITABLE_DEBUG_RECEIPT_PAGE', true );

Dies protokolliert kritische Ereignisse wie die Aktivierung von Fallbacks, Fehler bei der Seitenerstellung und die Behandlung von Theme-Wechseln in Ihrem WordPress-Debug-Log (erfordert, dass WP_DEBUG_LOG aktiviert ist).

Zusammenfassung

Das automatische Belegseiten-System funktioniert nahtlos mit den meisten WordPress-Themes. Wenn ein Theme Rendering-Probleme aufweist, die eine automatische Erkennung verhindern, erstellt Charitable automatisch eine Fallback-Seite, um sicherzustellen, dass Belege immer korrekt angezeigt werden. Entwickler können dieses Verhalten mit den bereitgestellten Filtern anpassen, und das System stellt die Einstellungen beim Wechseln von Themes automatisch wieder her.