“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 autocompletado está soportado para:

• Campos de texto – Texto de una sola línea (sanitizado como texto).
• 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.

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.

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.

---

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.