“Autocompletado para Formularios de Donación” es una nueva funcionalidad que comenzó en Charitable Pro 1.8.13 y que te permite pre-rellenar campos de formularios de donación utilizando parámetros de URL. Cuando un donante abre una página de donación con la cadena de consulta correcta, campos como nombre, correo electrónico, dirección y campos de formulario personalizados (texto, radio, casilla de verificación, selección, dirección) se pueden rellenar automáticamente. Esto es útil para campañas de correo electrónico, páginas de destino o enlaces de sistemas externos donde deseas pasar datos del donante o del contexto al formulario.

Tabla de Contenidos

Requisitos

• Charitable Pro: Versión 1.8.13 o superior
• WordPress: Versión 6.2 o superior
• PHP: Versión 7.4 o superior

El autocompletado por URL debe estar habilitado por campaña (ver abajo). Funciona tanto con el formulario de donación estándar como con el Constructor de Formularios Visuales(campos personalizados, campos de dirección, radio, casilla de verificación, selección).

Habilitar Autocompletado por URL

1. Edita la campaña cuyo formulario de donación deseas autocompletar.
2. Abre el Constructor de Campañas (o el área de configuración/formulario donde se configura el formulario de donación).
3. Busca el interruptor Habilitar Autocompletado por URL (en las opciones de visualización del formulario, cerca de Habilitar Formulario Visual).
4. Activa Habilitar Autocompletado por URL y guarda la campaña.

Si el autocompletado por URL está deshabilitado para la campaña, los parámetros de consulta se ignoran y no se pre-rellenan campos. Cuando está habilitado, solo se utilizan los parámetros que coinciden con las claves de campo permitidas y pasan la sanitización.

Formato del Parámetro

• Prefijo: Por defecto, todos los parámetros de autocompletado deben usar el prefijo cf_.
  Ejemplo: ?cf_first_name=Jane&cf_last_name=Doe
• Clave de campo: Después del prefijo, el nombre del parámetro debe coincidir con la clave del campo del formulario (por ejemplo, first_name, last_name, email, o claves de campo personalizadas como field_7 para campos de Visual Form).
• Valor: El valor se sanitiza según el tipo de campo (texto, correo electrónico, URL, área de texto, etc.). Los valores que fallan la sanitización o exceden la longitud máxima se descartan.

URL de ejemplo:

https://yoursite.com/campaigns/my-campaign/?cf_first_name=Jane&cf_last_name=Doe&[email protected]

Opcional: Puedes eliminar el requisito del prefijo cf_ usando el filtro charitable_prefill_use_prefix (ver Recursos para desarrolladores). En ese caso, se leerían parámetros como ?first_name=Jane. Se recomienda usar el prefijo para evitar conflictos con otros plugins o variables de consulta de WordPress.

Tipos de Campo Soportados

El relleno previo es compatible con los tipos de campo siguientes, y solo con estos. Un tipo de campo que no aparece en la lista ignora el parámetro.

• Campos de texto – Texto de una sola línea (sanitizado como texto).
• Oculto – Transporta un valor que usted proporciona en lugar de uno que el donante escribe. Se aborda por su Nombre de campo en lugar de un ID de campo, por lo que un campo oculto llamado source se rellena con ?cf_source=. Requiere Charitable Pro 1.8.18 o superior.
• Radio – Valor de una opción; el valor de la URL debe coincidir con el valor de una opción para seleccionarla.
• Checkbox – Uno o más valores de opción. Usa una lista separada por comas en un solo parámetro para preseleccionar varias opciones (p. ej., cf_my_checkbox=opt1,opt2).
• Select – Valor de una sola opción (o el valor seleccionado para menús desplegables de selección única). Para selección múltiple, el mismo comportamiento separado por comas que el checkbox cuando sea aplicable.
• Campos de dirección – Se admiten subcampos con las claves: address, address_2, city, state, postcode, country.
  Ejemplo: ?cf_address=123+Main+St&cf_city=Boston&cf_state=MA&cf_postcode=02101&cf_country=US

Comportamiento adicional:

• Email – Los nombres de los parámetros que contienen email (p. ej., user_email, email) se sanitizan con sanitize_email().
• URL / sitio web – Las claves como url, website, o que contengan _url se sanitizan con esc_url_raw().
• Campos tipo textarea – Las claves como message, comment, notes, description, special_message usan sanitize_textarea_field().

Los campos que nunca se rellenan previamente (seguridad) incluyen: campaign_id, donation_amount, amount, gateway, password, campos de pago y nonce, y otras claves sensibles o internas. La lista completa puede ser ampliada o modificada por los desarrolladores (ver Recursos para desarrolladores).

Nombres de Parámetros y Ejemplos

Campos comunes del donante

Parámetro	Descripción	Valor de ejemplo
cf_first_name	Nombre del donante	Jane
cf_last_name	Apellido del donante	Doe
cf_user_email	Email del donante	[email protected]
cf_email	Clave de email alternativa (si el formulario la usa)	[email protected]

Campos de dirección

Parámetro	Descripción	Valor de ejemplo
cf_address	Dirección línea 1	123 Main St
cf_address_2	Dirección línea 2	Apt 4
cf_city	Ciudad	Boston
estado_cf	Estado/región	MA
código_postal_cf	Código postal	02101
país_cf	Código de país	US

Campos personalizados de Visual Form

• Los campos personalizados en el Generador de Formularios Visuales usan claves internas como field_7 (donde 7 es el ID del campo). Usa la misma clave con el prefijo cf_.
  Ejemplo: ?cf_field_7=Mi+valor
• En algunos contextos, también se acepta el ID numérico (por ejemplo,cf_7 puede corresponder a field_7). Prefiere cf_field_N para mayor claridad cuando lo documente tu formulario.
• Los campos ocultos son la excepción. Un campo oculto se aborda por el Nombre de campo que usted escribió en el constructor, no por un ID de campo. Un campo llamado source se rellena con ?cf_source=spring-appeal. El mismo nombre se utiliza para la entrada del formulario, el parámetro y la clave bajo la que se almacena el valor después de la donación, por lo que solo hay un nombre que recordar. Se aceptan URL completas, por lo que puede pasar una dirección de referencia completa en lugar de una cadena.

Radio y selección

• Usa el valor de opción exacto que aparece en el formulario.
  Ejemplo: para una selección de “País” con valor US, usa ?cf_country=US.

Casilla de verificación (múltiple)

• Usa un parámetro con valores de opción separados por comas.
  Ejemplo: para un campo de casilla de verificación con las opciones newsletter y updates, usa ?cf_interests=newsletter,updates(reemplaza interests con la clave de tu campo).

URL de ejemplo completa

https://yoursite.com/donate/?cf_first_name=Jane&cf_last_name=Doe&cf_user_email=jane%40example.com&cf_address=123+Main+St&cf_city=Boston&cf_state=MA&cf_postcode=02101&cf_country=US

Usa la codificación URL adecuada (por ejemplo, %20 para espacio, %40 para @ en el correo electrónico).

Seguridad y Límites

• Claves bloqueadas: Las claves sensibles e internas (por ejemplo, donation_amount, gateway, password, nonces) nunca se leen de la URL. El importe de la donación y el método de pago no se pueden pre Rellenar a través de la cadena de consulta.
• Parámetros máximos: El número de parámetros de pre Relleno leídos de la URL está limitado (por defecto 20). Esto se puede cambiar con el filtro charitable_prefill_max_params.
• Longitud máxima: Cada valor se trunca a una longitud máxima (por defecto 500 caracteres). Esto se puede cambiar con el filtro charitable_prefill_max_value_length.
• Sanitización: Todos los valores se sanitizan según el tipo de campo (texto, correo electrónico, URL, área de texto). Los resultados no válidos o vacíos después de la sanitización no se aplican.
• Por campaña: El pre Relleno solo se ejecuta cuando Habilitar pre Relleno de URL está activado para esa campaña. No se aplica ningún pre Relleno en campañas que lo tengan deshabilitado.

Dónde encontrar el valor posteriormente

Un valor rellenado previamente se guarda con la donación. Hay tres lugares para leerlo.

1. La pantalla de detalles de la donación. Abra la donación en Charitable > Donaciones y mire el panel de resumen a la derecha. El campo aparece debajo de su etiqueta con el valor capturado.
2. La exportación CSV de donaciones. En Charitable > Donaciones, abra el panel de Exportación y el campo aparece bajo Campos personalizados de formularios visuales. Una vez activada su opción de exportación, el valor llega como su propia columna encabezada con la etiqueta del campo.
3. Directamente, para desarrolladores. El valor se almacena como metadatos de publicación en la donación bajo el propio nombre del campo sin prefijo, por lo que un campo llamado source se convierte en metadatos de publicación source.

Elegir dónde aparece

La sección Opciones avanzadas de cada campo en el Constructor de Campañas controla esto.

Opción	Lo que hace	Predeterminado para un campo oculto
Habilitar en Exportación	Añade una columna a la exportación CSV de donaciones	Activado
Habilitar en Metadatos de Donación	Muestra el valor en la pantalla de detalles de la donación	Activado
Habilitar Etiquetas de Correo Electrónico	Crea una etiqueta de correo electrónico para usar en plantillas de correo electrónico	Desactivado
Enviar en Webhooks de Automatización	Incluye el campo en las cargas útiles de Conexión de Automatización	Desactivado

Ambas opciones predeterminadas están activadas para un campo oculto, porque un campo cuyo propósito es transportar información hacia adelante no es de mucha utilidad si la información no se puede leer.

Un campo oculto creado antes de Charitable Pro 1.8.18 es la excepción. Las versiones anteriores no tenían control para esto y almacenaban una configuración "desactivada" para cada campo oculto, por lo que Charitable lo trata como su preferencia en lugar de anularlo. Para empezar a exportar uno de esos campos, ábralo en el Constructor de Campañas, expanda Opciones avanzadas y active Habilitar en Exportación. Los campos ocultos añadidos a partir de la versión 1.8.18 se exportan por defecto.

Un campo que no capturó nada

Un campo que no capturó ningún valor no escribe ninguna fila, en lugar de una vacía. Si esperas un valor y el campo falta por completo en la donación, el valor no llegó. Comprueba primero el interruptor de prellenado de la URL de la campaña y luego que el nombre del parámetro coincida exactamente con el nombre del campo.

Registrar la página de referencia automáticamente

Si deseas que se registre la página de referencia sin añadir un parámetro a cada enlace, introduce la etiqueta de combinación {referrer} en el Valor del campo de un campo oculto en lugar de usar un parámetro de URL. Charitable lo rellena en el navegador, desde la página de la que procedía el donante.

Rellenarlo en el navegador en lugar de en el servidor es lo que lo hace seguro en un sitio con caché. Un valor calculado en el servidor se almacena en la caché de tu página junto con el resto de la página, por lo que cada donante después del primero sería registrado como si hubiera venido de donde lo hizo el primero. Como el navegador lo rellena, también funciona dentro de una ventana modal de donación. No se registra nada para un visitante con JavaScript desactivado, lo cual es deliberado: un valor en blanco es más útil que una respuesta segura pero incorrecta sobre el origen de una donación.

Solución de problemas

Los campos no se autocompletan

• Confirma que Habilitar pre Relleno de URL está activado para la campaña (Generador de Campañas → opciones del formulario).
• Comprueba que la URL utiliza el prefijo cf_ (p. ej., cf_first_name, no first_name) a menos que hayas deshabilitado el prefijo mediante un filtro.
• Asegúrate de que el nombre del parámetro coincide con la clave del campo (p. ej., user_email o email para el campo de correo electrónico, field_7 para un campo personalizado con ID 7).
• Para select/radio/checkbox, el valor debe coincidir exactamente con un valor de opción del formulario.

El valor está cortado o vacío

• Los valores se truncan a la longitud máxima (500 caracteres por defecto). Usa el filtro charitable_prefill_max_value_length si necesitas valores más largos.
• Si el valor está vacío después de la sanitización (p. ej., correo electrónico no válido), no se aplicará. Comprueba la codificación (p. ej. %40 para @ en correos electrónicos).

Los subcampos de dirección no se rellenan

• Usa las claves exactas: address, address_2, city, state, postcode, country. Tienen prefijo como otros parámetros: cf_address, cf_city, etc.
• Asegúrate de que el formulario de la campaña incluya campos de dirección y que la opción de prellenado de URL esté habilitada para la campaña.

Campos personalizados de Visual Form

• Usa el formato de clave field_N (p. ej. cf_field_7) donde N es el ID del campo personalizado. Comprueba el creador de formularios o inspecciona los atributos name del formulario para confirmar los IDs.

Recursos para desarrolladores

Filtros

• charitableprefilluse_prefix – apply_filters( 'charitable_prefill_use_prefix', true )
  Devuelve false para permitir parámetros sin el prefijo cf_ (p. ej. ?first_name=Jane). Por defecto true.
• charitableprefillenabled – apply_filters( 'charitable_prefill_enabled', $enabled, $campaign_id )
  Anula si el prellenado de URL está habilitado para una campaña. Devuelve true o false; devuelve null para usar la configuración guardada de la campaña.
• charitableprefillmax_params – apply_filters( 'charitable_prefill_max_params', 20 )
  Número máximo de parámetros de URL a leer para el prellenado. Por defecto 20.
• charitableprefillmaxvaluelength – apply_filters( 'charitable_prefill_max_value_length', 500, $field_key )
  Longitud máxima de caracteres por valor. Por defecto 500.
• charitableprefillblocked_keys – apply_filters( 'charitable_prefill_blocked_keys', $blocked_keys )
  Añade o elimina claves que nunca deben ser rellenadas desde la URL (p. ej., nombres de campos sensibles a la seguridad).
• charitableprefillsanitize_value – apply_filters( 'charitable_prefill_sanitize_value', $sanitized, $field_key, $value )
  Modifica el valor sanitizado antes de que se aplique al campo.

Clase y métodos

• CharitableFormPrefill::get_instance() – Devuelve la instancia singleton.
• getprefillvalues( $campaign_id ) – Devuelve una matriz de todos los valores de prellenado analizados (clave_campo => valor) para la solicitud y campaña actuales.
• getvalue( $key, $campaignid ) – Devuelve el valor de prellenado para una única clave de campo, o null si no está establecido. Maneja la asignación de claves numéricas / field_N para campos personalizados de Visual Form.
• isenabledforcampaign( $campaignid ) – Devuelve si el prellenado de URL está habilitado para la campaña dada.
• hasprefillparams() – Devuelve si la solicitud actual tiene parámetros de relleno previo en la URL (útil para la salida temprana).
• reset() – Borra los valores analizados en caché (p. ej. para pruebas).

Historial de versiones

Versi	Cambios
1.8.13	Cadena de consulta de URL para rellenar previamente campos del formulario de donación (texto, radio, casilla de verificación, selección, dirección). Prefijo cf_, alternancia por campaña, saneamiento por tipo de campo, claves bloqueadas y filtros.
1.8.18	Los campos ocultos se pueden prellenar, dirigiéndose por su Nombre de campo. Los valores capturados ahora se muestran en la pantalla de detalles de la donación y se pueden incluir como una columna de exportación CSV de donaciones, controlada por campo en Opciones avanzadas. Añade la etiqueta de combinación {referrer} para campos ocultos.

---

Para crear el formulario de donación y campos personalizados, consulta el Constructor Visual de Formularios y la documentación del formulario de donación.