Comment fonctionne la détection automatique de page de reçu
(Remarque : Ceci est pour Charitable Pro 1.8.10.5+).
Lorsque le paramètre « Page de reçu de don » est défini sur « Automatique » dans les paramètres de Charitable, le plugin crée et gère automatiquement les pages de reçu pour vos dons. Ce système fonctionne de manière transparente avec la plupart des thèmes WordPress, y compris les thèmes traditionnels (classiques) et les thèmes de blocs modernes.
En mode automatique, Charitable utilise les règles de réécriture de WordPress pour créer des URL personnalisées telles que /donation-receipt/1234/ qui affichent le contenu du reçu sans que vous ayez à créer une page physique. Le plugin gère tous les détails techniques en coulisses.
Thèmes compatibles avec le mode automatique
Au moment de la rédaction (version 1.8.10.5), les thèmes suivants ont été testés et fonctionnent correctement avec la détection automatique de page de reçu :
Thèmes de blocs (édition complète du site)
- Twenty Twenty-Three – Thème de blocs par défaut de WordPress
- Twenty Twenty-Four – Thème de blocs par défaut de WordPress
- Twenty Twenty-Five – Thème de blocs par défaut de WordPress
Thèmes classiques (modèles PHP traditionnels)
- Astra – Thème polyvalent populaire
- GeneratePress – Thème léger
- OceanWP – Thème polyvalent
Ces thèmes fonctionnent car ils prennent en charge correctement la hiérarchie de modèles standard de WordPress et les filtres de contenu, permettant à Charitable d'injecter le contenu du reçu au bon moment dans le processus de rendu de la page.
Thèmes nécessitant la création d'une page de secours
Certains thèmes ont des systèmes de rendu uniques qui empêchent la détection automatique de page de reçu de fonctionner correctement. Lorsque Charitable détecte ce problème, il crée automatiquement une page de secours pour garantir que les reçus s'affichent toujours correctement.
Twenty Twenty-Two est un thème de blocs qui utilise une approche de rendu de modèle différente de celle des thèmes par défaut de WordPress ultérieurs. Lorsque Charitable tente d'afficher une page de reçu, le système de modèles du thème ne reconnaît pas correctement le point de terminaison personnalisé du reçu, ce qui entraîne une page vierge.
Pourquoi il a besoin d'une page de secours : Le système de modèles de blocs du thème ne gère pas correctement les points de terminaison personnalisés, ce qui empêche le rendu du contenu du reçu. Charitable détecte cela et crée automatiquement une page WordPress physique avec le shortcode [donation_receipt], que le thème peut ensuite afficher correctement.
D'autres exemples documentés au moment de la rédaction incluent YITH Wonder. YITH Wonder est un thème premium axé sur WooCommerce avec un système de constructeur de pages personnalisé. Similaire à Twenty Twenty-Two, il présente des bizarreries de rendu qui empêchent la détection automatique de reçu de fonctionner.
Remarque : Lorsque Charitable crée une page de secours, il met automatiquement à jour vos paramètres pour utiliser cette page. Si vous passez plus tard à un autre thème, Charitable restaurera le paramètre « Automatique » si le nouveau thème est compatible avec le mode automatique.
Filtres pour développeurs
Charitable fournit plusieurs filtres qui permettent aux développeurs de personnaliser le comportement de la page de secours. Tous les filtres sont documentés ci-dessous avec leurs valeurs par défaut et leurs cas d'utilisation.
charitable_receipt_fallback_enabled
Par défaut : vrai
Objectif : Activer ou désactiver l'ensemble du système de création de pages de secours.
Quand l'utiliser : Si vous souhaitez désactiver complètement la création automatique de pages de secours, par exemple parce que vous gérez les pages de reçus via une solution personnalisée.
// Disable fallback page creation
add_filter( 'charitable_receipt_fallback_enabled', '__return_false' );charitable_receipt_fallback_should_activate
Par défaut : vrai
Paramètres :
$should_activate(bool) – Indique si le secours doit s'activer$current_setting(string) – Paramètre actuel de la page de reçus ('auto' ou ID de page)
Objectif : Contrôler si le système de secours doit s'activer lorsqu'une page vierge est détectée. Cela vous donne un contrôle précis sur le moment où les pages de secours sont créées.
Quand l'utiliser : Si vous souhaitez empêcher la création de secours dans des circonstances spécifiques, comme pendant le développement ou pour certains rôles d'utilisateurs.
// 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
Par défaut : 'page-reçu-don'
Objectif : Personnaliser le slug d'URL de la page de secours qui sera créée.
Quand l'utiliser : Si vous souhaitez que la page de secours ait une structure d'URL différente, ou si vous devez correspondre aux conventions de nommage des URL de votre site.
// Use a custom slug for the fallback page
add_filter( 'charitable_receipt_fallback_page_slug', function( $slug ) {
return 'receipt';
} );charitable_receipt_fallback_page_args
Par défaut :
array(
'post_title' => __( 'Donation Receipt', 'charitable-pro' ),
'post_content' => '[donation_receipt]',
'post_status' => 'publish',
'post_type' => 'page',
'post_name' => $page_slug, // Set automatically
)Objectif : Personnaliser les propriétés de la page de secours lors de sa création. Cela inclut le titre de la page, le contenu, le statut et d'autres propriétés de publication WordPress.
Quand l'utiliser : Si vous souhaitez personnaliser le titre de la page, ajouter du contenu personnalisé avant/après le shortcode, définir un modèle de page spécifique ou modifier toute autre propriété de page.
// 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
Par défaut : faux
Objectif : Contrôler si la page de secours doit être automatiquement supprimée lors du passage à un thème différent problématique.
Quand l'utiliser : Si vous souhaitez nettoyer automatiquement les pages de secours lorsqu'elles ne sont plus nécessaires. Par défaut, les pages sont conservées (mais les paramètres sont restaurés sur « Automatique ») afin que vous puissiez les examiner ou les supprimer manuellement.
// Automatically delete fallback page on theme switch
add_filter( 'charitable_receipt_fallback_delete_on_theme_switch', '__return_true' );Débogage
Si vous avez besoin de déboguer les problèmes de page de reçus, vous pouvez activer la journalisation détaillée en ajoutant ceci à votre fichier wp-config.php :
define( 'CHARITABLE_DEBUG_RECEIPT_PAGE', true );Cela enregistrera les événements critiques tels que l'activation du secours, les échecs de création de page et la gestion du changement de thème dans votre journal de débogage WordPress (nécessite que WP_DEBUG_LOG soit activé).
Résumé
Le système automatique de page de reçus fonctionne de manière transparente avec la plupart des thèmes WordPress. Lorsqu'un thème présente des problèmes de rendu qui empêchent la détection automatique, Charitable crée automatiquement une page de secours pour garantir que les reçus s'affichent toujours correctement. Les développeurs peuvent personnaliser ce comportement à l'aide des filtres fournis, et le système restaure automatiquement les paramètres lors du changement de thème.
