La clase Charitable_Donation_Field te permite crear nuevos campos de donación o editar los existentes.
Tabla de Contenidos
Uso
Crear un nuevo campo de donación
Si deseas añadir un nuevo campo de donación, primero necesitarás crear una nueva instancia de Charitable_Donation_Field y luego registrarla en el Registro de Campos de Donación.
add_action( 'init', function() {
/* Create the Donation Field instance. */
$field = new Charitable_Donation_Field(
'my_custom_field',
array(
'label' => __( 'My Custom Field' ),
'data_type' => 'meta',
'value_callback' => false,
'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' ),
),
)
);
/* Register it. */
charitable()->donation_fields()->register_field( $field );
} );Obtener un campo de donación existente
Si deseas editar o modificar un campo de donación existente, la mejor manera de hacerlo es obteniendo el objeto del campo de donación registrado.
Luego puedes usar set() o el setter mágico para actualizar la definición del campo, o usar el getter mágico para obtener información sobre el campo.
/* Get the Donation Fields Registry. */
$fields = charitable()->donation_fields();
/* Get the Phone field. */
$field = $fields->get_field( 'phone' );
/* Change the label (magic setter). */
$field->label = 'Mobile No.';
/* Change the field to be required. */
$field->set( 'donation_form', 'required', true );
/* Print out the field's label (magic getter). */
echo $field->label;Propiedades
La clave o identificador del campo. Cada campo debe tener una clave única.
La etiqueta del campo. Esta es una descripción del campo. Esto es lo que se usará en el formulario de donación (a menos que lo anules específicamente en el argumento donation_form), en el área de detalles de donación del administrador y en la exportación de donaciones como encabezado de columna.
El tipo de datos que representa este campo. Hay dos opciones principales, con una tercera utilizada principalmente para fines internos de Charitable:
user: Esta es información específica del donante y generalmente seguirá siendo cierta para el donante en donaciones posteriores. Ejemplos de esto incluirían su nombre, número de teléfono, etc.meta: Esta es información específica de la donación. Un ejemplo de esto sería la pasarela de pago utilizada para la donación, o si el donante desea que esta donación se realice de forma anónima.core: Esto se utiliza principalmente para fines internos y no debe usarse en la mayoría de los casos. Si lo usas, deberás asegurarte de escribir código adicional para almacenar el valor del campo, así como para recuperarlo de la base de datos.
callback_valor (false|callable)
Cómo se recuperará el valor del campo. Si lo omites o lo estableces en false, se utilizará la devolución de llamada predeterminada según el tipo de datos del campo:
- Para un campo
meta, la devolución de llamada de valor predeterminada escharitable_get_donor_meta_value. - Para un campo
user, la devolución de llamada de valor predeterminada escharitable_get_donation_meta_value.
Puedes especificar tu propia devolución de llamada de valor pasando el nombre de tu propia función, una matriz que representa un método de objeto [$class_name, $method_name], o una función anónima.
formulario_donacion (false|array)
Cómo/si el campo se incluirá en el formulario de donación. Si se omite o se establece en false, el campo no se incluirá en el formulario de donación en absoluto. Al pasar una matriz, los siguientes argumentos están disponibles:
label (string)
La etiqueta que se muestra en el formulario de donación. Si se omite, se utilizará la propiedadlabeldel campo.type (string)El tipo de campo. Las opciones incluyen:textocorreo electrónicocontraseñafechaselector de fechacasilla de verificacióncasillas de verificación múltiplesseleccionarradioarchivoconjunto de camposeditor(usa el Editor clásico de WordPress)área de textonúmeroimagenurloculto
required (boolean)Indica si este es un campo obligatorio.options (array)Proporciona un conjunto de opciones. Esto es necesario cuandotypees uno deselect,radioomulti-checkbox. Estas deben proporcionarse en un array simple de valor => etiqueta, donde la etiqueta es lo que la gente ve al seleccionar una opción y el valor es lo que se almacena en la base de datos.default (mixed)
El valor predeterminado para este campo.placeholder (string)Un marcador de posición que se muestra en el campo cuando está vacío.min (int)Establece el número mínimo permitido. Solo aplicable sitypeesnumber.max (int)Establece el número máximo permitido. Solo aplicable sitypeesnumber.attrs (array)
Un array de atributos arbitrarios que se añadirán al campo de entrada.section (string)
La sección del formulario de donación en la que debe aparecer este campo. Hay dos secciones por defecto:userymeta. Si no se establece, la sección se basará en el tipo de datos del campo.show_before (string)
Establece dónde debe añadirse el campo en el formulario de donación especificando el campo antes del cual debe aparecer.show_after (string)
Establece dónde debe añadirse el campo en el formulario de donación especificando el campo después del cual debe aparecer.priority (int)
Establece la posición del campo dentro del formulario. Esto se utiliza a menos que se establezcanshow_afteroshow_beforepara el campo. Si no se establecenpriority,show_afteryshow_before, el campo se mostrará después del campo del formulario registrado más recientemente.value_callback (false|callable)
Una función de devolución de llamada para obtener el valor del campo para una donación. Esto anulará la configuraciónvalue_callbackpara el campo.
Indica si el campo debe mostrarse en el formulario de donación de administración.
- Si se establece en
false, el campo no se mostrará en el formulario de donación del administrador (ni siquiera como un campo oculto). - Si se establece en
true, el campo del formulario heredará los argumentos dedonation_form(si se proporcionan) o utilizará los argumentos predeterminados. - Alternativamente, puede pasar una matriz de valores para ajustar cómo se muestra este campo en el formulario de administración (se aceptan los mismos argumentos que para
donation_formanteriormente).
Si se incluye en la sección “Detalles de la donación” de la página de detalles de una donación individual en el administrador.
Si se incluye en la exportación de donaciones disponible en Charitable > Donaciones.
Si se crea una etiqueta de correo electrónico para este campo.
- Si se establece en
false, no se creará ninguna etiqueta de correo electrónico. - Si se establece en
true, se creará una etiqueta de correo electrónico, utilizando la etiqueta del campo como descripción. No se establecerá ningún valor de vista previa. - Alternativamente, pase una matriz para un control más detallado sobre los detalles de la etiqueta de correo electrónico:
description (cadena)
La descripción que se muestra para la etiqueta de correo electrónico. Si no se establece ninguna descripción, se utilizará lalabeldel campo.tag (cadena)
La etiqueta de correo electrónico. Si no se proporciona, se utilizará la clave del campo.preview (mixto)
Un valor que se utilizará en las vistas previas de correo electrónico para este campo.
Métodos
require()
Añadido en la versión 1.5.0
Crear una nueva instancia de Donation Field.
Argumentos
$field (cadena)La clave única del campo.
$argumentos (matriz)Una matriz que contiene cualquiera de las propiedades que se muestran arriba, excepto
$field.
Uso
$field = new Charitable_Donation_Field(
'my_custom_field',
array(
'label' => __( 'My Custom Field' ),
'data_type' => 'meta',
'value_callback' => false,
'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' ),
),
)
);
require()
Añadido en la versión 1.6.0
Cambiar un argumento del campo.
Argumentos
key (cadena)El argumento del campo a cambiar. Puede ser cualquiera de las propiedades descritas anteriormente, excepto
$field:label,data_type,value_callback,donation_form,admin_form,show_in_meta,show_in_export,email_tag.setting (cadena)Esto identifica un elemento específico de una matriz dentro de uno de los argumentos compatibles con matrices:
donation_form,admin_form,email_tag. Nota: Si$keyno es uno de esos tres, déjelo como una cadena vacía.$value (mixto)El nuevo valor para este argumento de campo.
Uso
/* Get the State field. */ $field = charitable()->donation_fields()->get_field( 'state' ); /* Change the label to Province. */ $field->set( 'label', '', 'Province' ); /* Change the field to be required. */ $field->set( 'donation_form', 'required', true );
require()
Añadido en la versión 1.5.0
Cambiar los parámetros del campo. A diferencia del método set() descrito anteriormente, este no permite actualizar un solo elemento dentro de un argumento similar a una matriz (por ejemplo, no se puede usar para cambiar fácilmente si un campo es obligatorio en el formulario de donación).
Es el equivalente a llamar a set() con el argumento $setting dejado como una cadena vacía.
Nota: __set() es un método mágico en PHP. Se llama implícitamente cuando intentas establecer una de las propiedades de la clase, distinta de $field.
Argumentos
$clave (string)El argumento de campo a cambiar. Puede ser cualquiera de las propiedades descritas anteriormente, excepto
$field:label,data_type,value_callback,donation_form,admin_form,show_in_meta,show_in_export,email_tag.$value (mixto)El nuevo valor para este argumento de campo.
Uso
/* Get the State field. */ $field = charitable()->donation_fields()->get_field( 'state' ); /* Change the label to Province. */ $field->label = 'Province';
require()
Añadido en la versión 1.5.0
Obtener el valor del campo para un argumento particular.
Nota: __get() es un método mágico en PHP. Se llama implícitamente cuando intentas acceder a una propiedad de la clase.
Argumentos
$clave (string)El argumento de campo a recuperar.
Uso
/* Get the State field. */ $field = charitable()->donation_fields()->get_field( 'state' ); /* Print/echo the current label. */ echo $field->label;
