La API de Campos de Donación proporciona una forma potente y flexible de añadir, eliminar y editar tus campos de donación.

• ¿Qué son los campos de donación?
• ¿Cómo obtengo el valor de un campo en particular?
• ¿Cómo añado un nuevo campo a mi formulario de donación?
• ¿Cómo cambio un campo de donación existente?
• ¿Cómo añado un campo de donación a una campaña específica?
• ¿Cómo cambio un campo de donación para una campaña en particular?
• ¿Cómo hago que un campo se muestre condicionalmente?
• Lista completa de campos de donación predeterminados

¿Qué son los campos de donación?

Los campos de donación son cualquier dato sobre una donación que esté disponible para que lo utilices. Por ejemplo, aquí tienes algunos de los campos disponibles por defecto:

• first_name – Obtiene el nombre del donante.
• last_name – Obtiene el apellido del donante.
• amount_formatted – Obtiene el importe de la donación, formateado según la configuración de divisa de tu sitio (p. ej. 50,00 $).
• date – La fecha en que se realizó la donación.
• gateway_label – El método de pago que utilizó el donante.

¿Cómo obtengo el valor de un campo de donación en particular?

Puedes obtener el valor de cualquier campo de donación a través del objeto Charitable_Donation de la donación.

El primer paso es obtener un objeto Charitable_Donation:

$donation_id = 123; // Replace with your Donation's ID.
$donation    = charitable_get_donation( $donation_id );

A continuación, puedes obtener el valor del campo llamando a get() en el objeto, como puedes ver en los siguientes ejemplos:

$first_name = $donation->get( 'first_name' );
$date       = $donation->get( 'date' );
$gateway    = $donation->get( 'gateway_label' );

Para juntarlo todo:

$donation_id = 123;
$donation    = charitable_get_donation( $donation_id );
$first_name  = $donation->get( 'first_name' );

¿Cómo añado un nuevo campo a mi formulario de donación?

Añadir un nuevo campo es un proceso de dos pasos.

Primero, crearás un nuevo objeto Charitable_Donation_Field que definirá los parámetros de tu campo: su etiqueta, el tipo de valor que almacena, cómo debe incluirse en el formulario de donación (si es que se incluye), si debe añadirse al archivo de exportación de donaciones, y más.

A continuación, añadirás este campo a la clase Charitable_Donation_Field_Registry, que proporciona una forma de almacenar y recuperar campos de donación.

Veamos cómo funciona esto en un ejemplo:

/**
 * Create a callback function on the `init` hook, where we
 * can register our donation field.
 */
add_action( 'init', function() {

    /* Create the `Charitable_Donation_Field` object. */
    $field = new Charitable_Donation_Field(
        'my_custom_field',
        array(
            'label'          => __( 'My Custom Field' ),
            'data_type'      => 'meta', 
            'donation_form'  => array(
                'type'       => 'text',
                'required'   => false,
                'show_after' => 'phone',
            ), 
            'admin_form'     => true,
            'show_in_meta'   => true,
            'show_in_export' => true,
            'email_tag'      => array(
                'description' => __( 'The custom field value' ),
            ),
        )
    );

    /* Get the `Charitable_Donation_Field_Registry` instance. */
    $fields = charitable()->donation_fields();

    /* Add the new field. */
    $fields->register_field( $field );
} );

En el ejemplo anterior, hemos creado un nuevo campo con la clave my_custom_field. Aquí tienes lo que significan sus parámetros definidos:

• Su etiqueta es “Mi Campo Personalizado”. Esto es lo que se utilizará en el formulario de donación, en el área de detalles de donación del administrador y en la exportación de donaciones como encabezado de columna.
• Su tipo de datos es meta. Esto significa que se almacenará como un campo meta específico para esa donación.
• Está configurado para mostrarse en el formulario de donación, justo después del campo phone. Es un campo opcional.
• También se añadirá al formulario de donación del administrador.
• Al ver los detalles de la donación, podrás ver lo que el donante introdujo para este campo en la sección “Detalles de la donación”.
• Al descargar una exportación de donaciones, se añadirá una nueva columna “Mi campo personalizado” que mostrará lo que los donantes introdujeron para este campo.
• Se ha creado una nueva etiqueta de correo electrónico para este campo, por lo que puedes incluirla fácilmente en correos electrónicos específicos de donaciones, como el Recibo de donación (para donantes) o la Notificación de donación (para administradores).

Este es un ejemplo relativamente simple, pero logra mucho. Haz clic aquí para un desglose más detallado de todos los parámetros disponibles al crear objetos Charitable_Donation_Field.

¿Cómo cambio un campo de donación existente?

Para cambiar un campo de donación existente, primero recuperas el campo del Charitable_Donation_Field_Registry y luego actualizas el valor del campo.

Para actualizar el valor del campo, podemos llamar a set() en el campo o usar el setter mágico.

/**
 * Create a callback function on the `init` hook, where we
 * can start changing the donation field.
 */
add_action( 'init', function() {

    /* Get the Donation Field Registry object. */
    $fields = charitable()->donation_fields();

    /* Get the field we want to change. */
    $field  = $fields->get_field( 'phone' );
    
    /**
     * Change #1: Make it a required field (uses set()).
     * Change #2: Change the label (uses magic setter).
     */
    $field->set( 'donation_form', 'required', true );
    $field->label = 'Phone Number';
} );

Para más información sobre cómo actualizar los argumentos del campo, consulta la referencia detallada de esos métodos de clase:

• Charitable_Donation_Field::set()
• Charitable_Donation_Field::__set() (setter mágico).

¿Cómo añado un campo a un formulario de donación de una campaña específica?

Si quieres que un campo nuevo o existente solo se muestre para ciertas campañas, puedes hacerlo añadiendo una nueva función que controle si el campo se muestra en el formulario de donación.

Si estás añadiendo un campo nuevo, primero tendrás que crear el campo de donación, así que sigue esos pasos primero.

Ahora puedes *ocultar* el campo que registraste de todos los formularios de donación excepto del que quieres que se muestre:

add_filter( 'charitable_donation_form_user_fields', function( $fields, $form ) {

    /* If the field doesn't exist, stop right here. */
    if ( ! array_key_exists( 'my_custom_field', $fields ) ) {
        return $fields;
    }

    /* Match any campaign that DOESN'T have a slug of 'special-campaign' */
    if ( 'special-campaign' !== $form->get_campaign()->post_name ) {    
        unset( $fields['my_custom_field'] );
    }
    
    return $fields;
}, 10, 2 );

¿Qué está pasando aquí?

• Solo queremos que el campo my_custom_field se muestre en la campaña con un slug de ‘special-campaign’.
• El campo se mostrará en todas las campañas por defecto, así que nuestro código comprueba si la campaña *no* tiene un slug de ‘special-campaign’ y luego la elimina.

Puedes cambiar la condición bajo la cual se muestra el campo. Por ejemplo, puedes cambiar el campo para que solo se muestre para campañas de una categoría determinada, o para campañas que tengan una campaña principal específica (es decir, recaudaciones de fondos para una de tus campañas de recaudación de fondos de persona a persona).

¿Cómo cambio un campo de donación para una campaña en particular?

El enfoque utilizado anteriormente para mostrar un campo en una campaña en particular se puede adaptar para *cambiar* un campo de donación para una campaña en particular.

Por ejemplo, si solo quieres aceptar donaciones de donantes de un país específico para una campaña determinada, puedes lograrlo con el siguiente código:

add_filter( 'charitable_donation_form_user_fields', function( $fields, $form ) {
    /* If a country field doesn't exist, stop right here. */
    if ( ! array_key_exists( 'country', $fields ) ) {
        return $fields;
    }

    if ( 'south-africa-only' === $form->get_campaign()->post_name ) {
        $fields['country']['options'] = array(
            'ZA' => 'South Africa',
        );
    }	

    return $fields;

}, 10, 2 );

Este código hará que la campaña con el slug ‘south-africa-only’ solo muestre Sudáfrica como opción de país válida.

¿Cómo hago que un campo de donación se muestre según la entrada del usuario?

Los dos ejemplos anteriores mostraron cómo añadir/cambiar campos de donación basándose en la campaña del formulario de donación. Pero, ¿y si quieres mostrar u ocultar un campo basándote en la entrada del usuario?

Gestionar esto requiere un enfoque diferente, utilizando Javascript. Si eres un desarrollador con confianza, puedes añadir esto a través de un nuevo archivo Javascript, pero en el ejemplo a continuación utilizaremos la función wp_add_inline_script para añadir nuestro Javascript personalizado sin necesidad de crear, registrar y poner en cola un nuevo script.

En el ejemplo a continuación, solo mostramos nuestro campo personalizado, my_custom_field, cuando el donante es de los Estados Unidos:

add_action( 'wp_enqueue_scripts', function() {
    wp_add_inline_script( 'charitable-script', "
        jQuery('body').on('charitable:form:loaded', (event, donationForm) => {
            var countryField = donationForm.get_input('country');
            function toggleCustomField() {
                donationForm.get_input('my_custom_field').parent().toggle('US' === countryField.val());
            }
            countryField.on('change', toggleCustomField).trigger('change');
        });
    " );
} );

Lista completa de campos de donación predeterminados

Los siguientes campos son añadidos por Charitable y sus extensiones:

Clave	Descripción
donation_id	El ID de la donación
nombre	El nombre del donante.
apellido	El apellido del donante.
donante	El nombre completo del donante.
correo electrónico	La dirección de correo electrónico del donante.
direccion_donante	La dirección completa del donante, formateada.
direccion	El primer campo de la dirección del donante.
direccion_2	El segundo campo de la dirección del donante.
ciudad	La ciudad del donante.
provincia	El estado del donante.
codigo_postal	El código postal del donante.
pais	El país del donante.
telefono	El número de teléfono del donante.
campanas	La campaña que recibió la donación.
lista_categorias_campanas	Las categorías en las que se encuentra la campaña.
importe_formateado	El importe de la donación, formateado según la configuración de su divisa.
fecha	La fecha de la donación.
hora	La hora en que se realizó la donación.
estado	El estado de la donación. Devuelve el valor crudo de post_status.
etiqueta_estado	El estado de la donación como una etiqueta más legible.
pasarela_donacion	La pasarela de pago utilizada para la donación.
etiqueta_pasarela	La pasarela de pago como una cadena de texto fácil de leer.
clave_donacion	La clave única de la donación.
id_transaccion_pasarela	El ID de transacción de la donación en la pasarela de pago utilizada (por ejemplo, PayPal, Stripe).
modo_prueba	Si la donación se realizó en modo de prueba.
resumen_donacion	Un resumen legible de la donación, que indica la campaña que recibe la donación y el importe donado.
consentimiento_contacto	Si el donante dio su consentimiento para ser contactado.
cubrir_comisiones	Si el donante cubrió las comisiones. Añadido por Fee Relief.
importe_comision	El importe de las comisiones de procesamiento pagadas por el donante. Añadido por Fee Relief.
importe_comision_formateado	El importe de las comisiones de procesamiento pagadas por el donante, formateado según la configuración de su divisa. Añadido por Alivio de comisiones.
donacion_total_con_comisiones	El importe total de la donación, incluidas las comisiones de procesamiento. Añadido por Alivio de comisiones.
donacion_total_con_comisiones_formateada	El importe total de la donación, incluidas las comisiones de procesamiento, formateado según la configuración de su divisa. Añadido por Alivio de comisiones.
consentimiento para rastrear	Si el donante ha dado permiso para rastrear la actividad de su boletín (aperturas, clics). Esto solo se aplica si está utilizando Campaign Monitor. Añadido por Conexión de boletines.
donación anónima	Si el donante ha optado por permanecer en el anonimato. Añadido por Donaciones anónimas.
comentario del donante	El comentario dejado por el donante. Añadido por Comentarios de donantes.
Gift Aid	Si el donante reclamó la desgravación fiscal. Añadido por Gift Aid.
declaración de Gift Aid	La declaración que el donante aceptó al reclamar la desgravación fiscal. Añadido por Gift Aid.
título	El título del donante (Sr., Sra., Srta., etc.). Añadido por Gift Aid.
dirección 3	La tercera línea de la dirección del donante. Añadido por Gift Aid.