¿Te gustaría que un campo personalizado de tu formulario de donación apareciera en el recibo PDF? Cuando agregas un campo personalizado a un formulario heredado o creas uno en el constructor visual de campañas, Charitable guarda la respuesta del donante con la donación, pero la plantilla del recibo PDF no la imprime automáticamente. Necesitarás indicar al recibo dónde se encuentra el valor y cómo mostrarlo.

Esta guía te guiará a través de los pasos para agregar un campo de donación personalizado a tu recibo PDF, ya sea que el campo provenga de un formulario heredado o del constructor visual de formularios.

Nota: Esta sección asume que estás utilizando Charitable Pro 1.8.13+ e implica una pequeña cantidad de PHP. Si no te sientes cómodo editando código, pega el fragmento en una herramienta como WPCode para no tener que tocar los archivos del tema directamente, o entrégaselo a tu desarrollador.

¿Cómo se almacenan los campos personalizados?

Antes de poder mostrar un campo en el recibo, necesitas dos cosas: dónde se almacena su valor y por qué clave buscarlo. Charitable guarda los campos personalizados de formularios heredados y de formularios visuales como metadatos de la publicación de donación, pero la clave de metadatos se ve diferente dependiendo de qué formulario la creó.

Para campos personalizados de formularios heredados, la clave de metadatos es la que se registró con el campo. Si registraste un campo con la clave t_shirt_size usando la API de Campos de Donación, el valor se almacena bajo esa clave exacta.

Para campos personalizados de formularios visuales, la clave utiliza el formato field_X, donde X es el ID numérico que el constructor de campañas asignó al campo. Los campos ocultos son la excepción: esos usan el nombre que escribiste en la configuración de Nombre del campo.

Encontrar la clave de metadatos de tu campo

La forma más fácil de confirmar qué clave de metadatos utiliza un campo es mirar una donación real que incluyó el campo.

Para un formulario heredado, la clave de metadatos es la clave de matriz que usaste al registrar el campo con el filtro charitable_default_donation_fields. Si no escribiste el fragmento tú mismo, puedes buscar en tu sitio (o preguntar a tu desarrollador) ese filtro para confirmar la clave.

Para un formulario visual, ve a Charitable » Donaciones, abre una donación de prueba que haya enviado el campo personalizado y busca en los datos guardados de la donación entradas como field_3 o field_5. El número es el ID del campo en el constructor. Si prefieres ver todas las claves de metadatos de un vistazo, puedes añadir temporalmente este fragmento a cualquier página de administración:

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

Nota: Una vez que hayas anotado las claves que necesitas, elimina el fragmento; dejar llamadas print_r() en la salida de producción es un desastre y puede filtrar datos de donantes.

Agregar un campo usando un hook (recomendado)

Charitable dispara una acción llamada charitable_pdf_receipt_after_donor_details justo después del bloque de detalles del donante en cada recibo PDF. Engancharse a esta acción es la forma más sencilla de añadir un campo personalizado, ya que no tiene que sobrescribir ningún archivo de plantilla – sus cambios sobreviven a las actualizaciones del plugin sin trabajo adicional.

Para activar el fragmento, péguelo en el archivo functions.php de su tema hijo o en un plugin de fragmentos de código:

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

El ejemplo imprime el campo debajo del nombre, dirección y correo electrónico del donante. Al adaptarlo, reemplace la clave meta, la etiqueta visible y el marcado para que coincidan con el campo que está añadiendo.

Nota: Si su valor contiene HTML – por ejemplo, la salida de un campo de texto largo – use wp_kses_post() en lugar de esc_html() para que las etiquetas de formato básicas sobrevivan.

Añadir un campo sobrescribiendo la plantilla

Si necesita colocar el campo en otro lugar que no sea después de los detalles del donante – por ejemplo, dentro de la tabla de donaciones o en el pie de página – puede sobrescribir la plantilla del recibo PDF.

Las plantillas PDF de Charitable se pueden sobrescribir desde el tema. Para personalizar el diseño principal del PDF, copie este archivo:

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

En su tema activo en esta ruta:

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

Una vez que su copia esté en su lugar, Charitable la cargará en lugar de la versión del plugin. El mismo patrón de ruta funciona para las dos plantillas parciales que llama pdf.php:

• Detalles del donante: templates/pro/pdf-receipts/donation-receipt/donor-details.php
• Detalles de la donación: templates/pro/pdf-receipts/donation-receipt/details.php

Dentro de cualquier plantilla copiada, la variable $donation es el objeto completo Charitable_Donation. Para obtener el valor de un campo personalizado, use la misma llamada a get_post_meta() del método anterior, luego agregue el marcado donde quiera que aparezca el valor:

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

Nota: Las sobrescrituras de plantillas deben revisarse cada vez que actualice Charitable Pro. Si la versión del plugin de la plantilla incorpora nuevas características o correcciones de errores, su sobrescritura no las verá automáticamente. El método de gancho anterior evita esto por completo, así que use una sobrescritura de plantilla solo cuando necesite control sobre la ubicación.

Previsualizando sus cambios

Una vez que su fragmento o sobrescritura de plantilla se guarde, genere un PDF real para confirmar que el campo aparece como se espera. Desde la pantalla Charitable » Donaciones, elija una donación que incluyera el campo personalizado, luego haga clic en el icono PDF junto a ella para descargar el recibo. Si el campo no aparece, revise estas comprobaciones una por una:

• Confirme que la clave meta coincide exactamente – field_3 y field_03 no son lo mismo.
• Verifique que la donación que está probando realmente envió un valor para el campo. Los valores vacíos no se imprimirán.
• Intente con una donación de prueba diferente para descartar que una entrada esté vacía.

Nota: Los valores de los campos que parezcan vacíos en la pantalla de administración de donaciones también estarán vacíos en el PDF. El recibo no puede mostrar datos que la donación nunca recopiló.