Cómo funciona la detección automática de páginas de recibo
(Nota: Esto es para Charitable Pro 1.8.10.5+).
Cuando la configuración "Página de recibo de donación" se establece en "Automático" en la configuración de Charitable, el plugin crea y administra automáticamente las páginas de recibo para tus donaciones. Este sistema funciona a la perfección con la mayoría de los temas de WordPress, incluidos los temas tradicionales (clásicos) y los temas de bloques modernos.
En modo automático, Charitable utiliza las reglas de reescritura de WordPress para crear URL personalizadas como /donation-receipt/1234/ que muestran el contenido del recibo sin necesidad de que crees una página física. El plugin se encarga de todos los detalles técnicos entre bastidores.
Temas que funcionan con el modo automático
En el momento de escribir esto (versión 1.8.10.5), los siguientes temas han sido probados y funcionan correctamente con la detección automática de páginas de recibo:
Temas de bloques (Edición completa del sitio)
- Twenty Twenty-Three – Tema de bloques predeterminado de WordPress
- Twenty Twenty-Four – Tema de bloques predeterminado de WordPress
- Twenty Twenty-Five – Tema de bloques predeterminado de WordPress
Temas clásicos (Plantillas PHP tradicionales)
- Astra – Popular tema multipropósito
- GeneratePress – Tema ligero
- OceanWP – Tema multipropósito
Estos temas funcionan porque admiten correctamente la jerarquía de plantillas estándar de WordPress y los filtros de contenido, lo que permite a Charitable inyectar el contenido del recibo en el momento adecuado del proceso de renderizado de la página.
Temas que requieren la creación de una página de reserva
Algunos temas tienen sistemas de renderizado únicos que impiden que la detección automática de páginas de recibo funcione correctamente. Cuando Charitable detecta este problema, crea automáticamente una página de reserva para garantizar que los recibos se muestren correctamente.
Twenty Twenty-Two es un tema de bloques que utiliza un enfoque de renderizado de plantillas diferente al de los temas predeterminados posteriores de WordPress. Cuando Charitable intenta mostrar una página de recibo, el sistema de plantillas del tema no reconoce correctamente el punto final del recibo personalizado, lo que resulta en una página en blanco.
Por qué necesita una reserva: El sistema de plantillas de bloques del tema no maneja correctamente los puntos finales personalizados, lo que provoca que el contenido del recibo no se renderice. Charitable detecta esto y crea automáticamente una página física de WordPress con el shortcode [donation_receipt], que el tema puede mostrar correctamente.
Otros ejemplos documentados en el momento de escribir esto incluyen YITH Wonder. YITH Wonder es un tema premium centrado en WooCommerce con un sistema de constructor de páginas personalizado. Similar a Twenty Twenty-Two, tiene peculiaridades de renderizado que impiden que la detección automática de recibos funcione.
Nota: Cuando Charitable crea una página de reserva, actualiza automáticamente tu configuración para usar esa página. Si cambias a un tema diferente más adelante, Charitable restaurará la configuración "Automático" si el nuevo tema funciona con el modo automático.
Filtros para desarrolladores
Charitable proporciona varios filtros que permiten a los desarrolladores personalizar el comportamiento de la página de reserva. Todos los filtros se documentan a continuación con sus valores predeterminados y casos de uso.
charitable_receipt_fallback_enabled
Predeterminado: verdadero
Propósito: Habilitar o deshabilitar todo el sistema de creación de páginas de reserva.
Cuándo usar: Si desea deshabilitar completamente la creación automática de páginas de reserva, quizás porque está gestionando las páginas de recibos a través de una solución personalizada.
// Disable fallback page creation
add_filter( 'charitable_receipt_fallback_enabled', '__return_false' );charitable_receipt_fallback_should_activate
Predeterminado: verdadero
Parámetros:
$should_activate(bool) – Si la reserva debe activarse$current_setting(string) – Configuración actual de la página de recibo ('auto' o ID de página)
Propósito: Controlar si el sistema de reserva debe activarse cuando se detecta una página en blanco. Esto le da un control detallado sobre cuándo se crean las páginas de reserva.
Cuándo usar: Si desea evitar la creación de reservas en circunstancias específicas, como durante el desarrollo o para ciertos roles de usuario.
// 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
Predeterminado: 'pagina-recibo-donacion'
Propósito: Personalizar el slug de la URL para la página de reserva que se crea.
Cuándo usar: Si desea que la página de reserva tenga una estructura de URL diferente, o si necesita que coincida con las convenciones de nomenclatura de URL de su sitio.
// Use a custom slug for the fallback page
add_filter( 'charitable_receipt_fallback_page_slug', function( $slug ) {
return 'receipt';
} );charitable_receipt_fallback_page_args
Predeterminado:
array(
'post_title' => __( 'Donation Receipt', 'charitable-pro' ),
'post_content' => '[donation_receipt]',
'post_status' => 'publish',
'post_type' => 'page',
'post_name' => $page_slug, // Set automatically
)Propósito: Personalizar las propiedades de la página de reserva cuando se crea. Esto incluye el título de la página, el contenido, el estado y otras propiedades de la publicación de WordPress.
Cuándo usar: Si desea personalizar el título de la página, agregar contenido personalizado antes/después del shortcode, establecer una plantilla de página específica o modificar cualquier otra propiedad de la página.
// 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
Predeterminado: false
Propósito: Controlar si la página de reserva debe eliminarse automáticamente al cambiar a un tema que no sea el problemático.
Cuándo usar: Si desea limpiar automáticamente las páginas de reserva cuando ya no sean necesarias. Por defecto, las páginas se conservan (pero la configuración se restaura a "Automático") para que pueda revisarlas o eliminarlas manualmente.
// Automatically delete fallback page on theme switch
add_filter( 'charitable_receipt_fallback_delete_on_theme_switch', '__return_true' );Depuración
Si necesita depurar problemas con la página de recibos, puede habilitar el registro detallado agregando esto a su archivo wp-config.php:
define( 'CHARITABLE_DEBUG_RECEIPT_PAGE', true );Esto registrará eventos críticos como la activación de la reserva, fallos en la creación de páginas y el manejo del cambio de tema en el registro de depuración de su WordPress (requiere que WP_DEBUG_LOG esté habilitado).
Resumen
El sistema automático de páginas de recibos funciona perfectamente con la mayoría de los temas de WordPress. Cuando un tema tiene problemas de renderizado que impiden la detección automática, Charitable crea automáticamente una página de reserva para garantizar que los recibos se muestren siempre correctamente. Los desarrolladores pueden personalizar este comportamiento utilizando los filtros proporcionados, y el sistema restaura automáticamente la configuración al cambiar de tema.
