El Creador de Formularios de Donación Visual es un creador de formularios de arrastrar y soltar que te permite crear formularios de donación personalizados para campañas. Este documento proporciona detalles técnicos para desarrolladores, diseñadores y desarrolladores de temas que trabajan con el sistema de creador de formularios visual.

---

Tabla de Contenidos

---

Ganchos y filtros

Los siguientes hooks y filtros de PHP están disponibles para extender y personalizar el creador de formularios visual:

Filtros de Tema y Estilo

• charitable_visual_form_theme_classes – Filtra las clases de tema visual resueltas (tema de densidad)
  • Parámetros: $result (array), $visual_theme (string)
  • Devuelve: Array con la clave density_theme
• charitable_visual_form_theme_variables – Filtra el mapa de variables de tema para formularios visuales
  • Parámetros: $result (array), $density_theme (string)
  • Devuelve: Array con la clave variables que contiene definiciones de variables CSS
• charitable_visual_form_default_styles – Filtra los estilos predeterminados para formularios visuales
  • Parámetros: $defaults (array), $context (string)
  • Devuelve: Array de valores de estilo predeterminados
• charitable_visual_form_styles – Filtra el array completo de estilos para un formulario
  • Parámetros: $styles (array), $campaign_id (int), $form_data (array)
  • Devuelve: Array de estilos modificado
• charitable_visual_form_field_styles – Filtra los estilos para campos individuales
  • Parámetros: $field_styles (array), $field_id (string), $field_data (array), $campaign_id (int)
  • Devuelve: Array de estilos de campo modificado
• charitable_visual_form_field_classes – Filtra las clases CSS aplicadas a los campos del formulario
  • Parámetros: $classes (array), $field_id (string), $field_data (array), $campaign_id (int)
  • Devuelve: Array de clases modificado
• charitable_visual_form_field_full_width – Determina si un campo debe ocupar todo el ancho
  • Parámetros: $is_full_width (bool), $field_id (string), $field_data (array), $campaign_id (int)
  • Devuelve: Booleano
• charitable_visual_form_enable_theme_inheritance – Habilita/deshabilita la herencia de estilos del tema
  • Parámetros: Ninguno
  • Devuelve: Booleano (por defecto: false)
• charitable_visual_form_detected_theme_styles – Filtra los estilos de tema detectados
  • Parámetros: $detected (array), $active_theme (string)
  • Devuelve: Array de estilos detectados modificado
• charitable_visual_form_theme_style_map – Mapea los estilos de tema detectados a las variables del formulario
  • Parámetros: $mapped (array), $detected_styles (array), $theme_name (string)
  • Devuelve: Array de mapeo modificado
• charitable_visual_form_theme_fallback – Proporciona valores de reserva para las variables del tema
  • Parámetros: $fallback (mixed), $form_variable (string), $detected_value (mixed), $context (string)
  • Devuelve: Valor de reserva o null
• charitable_visual_form_enable_elementor_inheritance – Habilita/deshabilita la herencia de estilos de Elementor
  • Parámetros: Ninguno
  • Devuelve: Booleano (por defecto: true)
• charitable_visual_form_detected_elementor_styles – Filtra los estilos de Elementor detectados
  • Parámetros: $detected (array), $elementor_active (bool)
  • Devuelve: Array de estilos detectados modificado
• charitable_visual_form_elementor_style_map – Mapea los estilos de Elementor a las variables del formulario
  • Parámetros: $mapped (array), $detected_styles (array)
  • Devuelve: Array de mapeo modificado

Filtros de formulario de varios pasos

• charitable_multistep_animation_type – Filtra el tipo de animación para formularios de varios pasos
  • Parámetros: $animation_type (string), $campaign_id (int)
  • Devuelve: Cadena de tipo de animación
• charitable_multistep_prev_button_text – Filtra el texto del botón “Anterior”
  • Parámetros: $text (string), $campaign_id (int)
  • Devuelve: Cadena de texto del botón
• charitable_multistep_next_button_text – Filtra el texto del botón “Siguiente”
  • Parámetros: $text (string), $campaign_id (int)
  • Devuelve: Cadena de texto del botón
• Filtros específicos de campo
• charitable_multistep_step_label – Filtra las etiquetas de los pasos
  • Parámetros: $label (string), $step_number (int), $campaign_id (int)
  • Devuelve: Cadena de etiqueta del paso

Acciones de formulario y campo

• charitable_donation_form_before_fields – Acción que se dispara antes de que se rendericen los campos del formulario
  • Parámetros: $current_form (array)
• charitable_visual_form_before_payment_section – Acción que se dispara antes de que se renderice la sección de pago
  • Parámetros: $current_form (array), $campaign_id (int), $visual_form_data (array), $section_index (int by reference)
• charitable_visual_form_file_uploaded – Acción que se dispara cuando se sube un archivo
  • Parámetros: $attachment_id (int), $donation_id (int), $file_key (string)

Filtros específicos del campo

• charitable_visual_form_address_country_default – Filtra el país predeterminado para los campos de dirección
  • Parámetros: $default_country (string), $campaign_id (int), $field_data (array)
  • Devuelve: Cadena de código de país
• charitable_donation_form_gateway_fields – Filtra los campos específicos de la pasarela
  • Parámetros: $gateway_fields (array), $gateway (object)
  • Devuelve: Matriz de campos de pasarela modificada
• charitable_html_field_allowed_html – Filtra las etiquetas HTML permitidas para los campos HTML
  • Parámetros: $allowed_html (string|array), $field_data (array), $field_id (string)
  • Devuelve: 'default' o matriz de HTML permitido
• charitable_checkbox_field_use_fieldset – Determina si los campos de casilla de verificación deben usar el contenedor fieldset
  • Parámetros: $use_fieldset (bool), $normalized_id (string), $render_data (array), $visual_field_data (array)
  • Devuelve: Booleano (por defecto: false)
• charitable_visual_form_donate_label – Filtra la etiqueta del botón donar
  • Parámetros: $donate_label (string), $campaign_id (int), $visual_form_data (array)
  • Devuelve: Cadena de etiqueta del botón

Filtros del constructor de formularios

• charitable_default_visual_form_template – Filtra la plantilla de formulario visual predeterminada
  • Parámetros: $default_template (array), $campaign_id (int), $form_type (string)
  • Devuelve: Matriz de plantilla
• charitable_form_builder_load_fields – Filtra la lista de tipos de campo a cargar
  • Parámetros: $form_fields (array)
  • Devuelve: Matriz de tipos de campo modificada
• charitable_builder_form_buttons – Filtra los botones de campo del formulario en la barra lateral del constructor
  • Parámetros: $fields (array)
  • Devuelve: Matriz de campos modificada
• charitable_builder_form_field_button_attributes – Filtra los atributos de los botones de campo del formulario
  • Parámetros: $attributes (array), $field (array), $form_data (array)
  • Devuelve: Matriz de atributos modificada
• charitable_visual_form_conditional_logic_enabled – Habilita/deshabilita la lógica condicional globalmente
  • Parámetros: $enabled (bool), $field_data (array)
  • Devuelve: Booleano (por defecto: true)
• charitable_visual_form_debug – Habilita/deshabilita el modo de depuración para formularios visuales
  • Parámetros: $enable_debug (bool)
  • Devuelve: Booleano

---

Categorías y Ajustes de Campos

Los campos en el constructor de formularios visuales se organizan en tres categorías: Campos obligatorios, Campos del formulario (normales) y Campos Pro.

Ajustes Comunes de Campos

La mayoría de los campos admiten la siguiente configuración común (nota: no todos los campos tienen todas estas configuraciones):

• Etiqueta – La etiqueta de texto que se muestra a los usuarios en el formulario de donación
• Marcador de posición – Texto de marcador de posición que se muestra en los campos de entrada vacíos
• Obligatorio – Si el campo debe rellenarse antes de enviar el formulario
• Alineación – Alineación del campo (izquierda, centro, derecha) – no disponible en todos los campos
• Clase CSS – Clases CSS personalizadas para estilizar – no disponible en todos los campos

Campos obligatorios

Estos campos son esenciales para los formularios de donación y, por lo general, solo se pueden agregar una vez por formulario.

Campos de nombre del donante

• Tipo: campos-nombre-donante
• Configuración:
  • Diseño (lado a lado o apilado)
  • Etiqueta
  • Alinear
  • Clase CSS
• Límite de campo: 1 por formulario
• No se puede duplicar

Campo de correo electrónico del donante

• Tipo: campo-correo-electronico-donante
• Configuración:
  • Etiqueta
  • Alinear
  • Clase CSS
• Límite de campo: 1 por formulario
• No se puede duplicar

Campos de dirección

• Tipo: campos-direccion
• Configuración:
  • Etiqueta
  • Alinear
  • Clase CSS
• Límite de campo: 1 por formulario
• No se puede duplicar
• Nota: Incluye campos de dirección, segunda línea de dirección, ciudad, estado, código postal y país

Política de Privacidad

• Tipo: politica-privacidad
• Configuración:
  • Etiqueta
  • Alinear
  • Clase CSS
• Límite de campo: 1 por formulario
• No se puede duplicar

Importes de donación

• Tipo: importes-donacion-sugeridos
• Configuración:
  • Etiqueta
  • Alinear
  • Clase CSS
• Límite de campo: 1 por formulario
• No se puede duplicar
• Nota: Muestra los importes de donación sugeridos de la configuración de la campaña

Sección de pago

• Tipo: seccion-pago
• Configuración:
  • Selección de pasarela (casillas de verificación de selección múltiple para las pasarelas de pago disponibles)
  • Etiqueta
  • Alinear
  • Clase CSS
• Límite de campo: 1 por formulario
• No se puede duplicar

Campos del Formulario (Regulares)

Estos son campos de formulario estándar disponibles para crear formularios de donación personalizados.

Campo de texto único

• Tipo: texto-unico
• Configuración:
  • Etiqueta
  • Marcador de posición
  • Requerido
  • Valor predeterminado
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo desplegable

• Tipo: desplegable
• Configuración:
  • Etiqueta
  • Marcador de posición
  • Requerido
  • Permitir selección múltiple (casilla de verificación)
  • Gestión de opciones (agregar/editar/eliminar opciones con pares de valor y etiqueta)
  • Opción predeterminada (selección de radio)
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo de casilla de verificación

• Tipo: campo-de-casilla-de-verificación
• Configuración:
  • Etiqueta
  • Requerido
  • Gestión de Opciones de Casillas de Verificación (añadir/editar/eliminar casillas de verificación con pares de valor y etiqueta)
  • Selecciones Predeterminadas (casillas de verificación para opciones preseleccionadas)
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo de Radio

• Tipo: campo-de-radio
• Configuración:
  • Etiqueta
  • Requerido
  • Gestión de Opciones de Radio (añadir/editar/eliminar botones de radio con pares de valor y etiqueta)
  • Selección Predeterminada (selección de radio)
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo de Área de Texto

• Tipo: campo-de-área-de-texto
• Configuración:
  • Etiqueta
  • Marcador de posición
  • Requerido
  • Filas (número de filas del área de texto)
  • Longitud Máxima (límite de caracteres)
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo de Correo Electrónico

• Tipo: campo-de-correo-electrónico
• Configuración:
  • Etiqueta
  • Marcador de posición
  • Requerido
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo de teléfono

• Tipo: campo-de-teléfono
• Configuración:
  • Etiqueta
  • Marcador de posición
  • Requerido
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo Numérico

• Tipo: campo-numérico
• Configuración:
  • Etiqueta
  • Marcador de posición
  • Requerido
  • Valor Mínimo (opcional)
  • Valor Máximo (opcional)
  • Paso (valor de incremento/decremento)
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo de Fecha

• Tipo: campo-de-fecha
• Configuración:
  • Etiqueta
  • Marcador de posición
  • Requerido
  • Formato de Fecha
  • Fecha Mínima (opcional)
  • Fecha Máxima (opcional)
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo de URL

• Tipo: campo-de-url
• Configuración:
  • Etiqueta
  • Marcador de posición
  • Requerido
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo de Archivo

• Tipo: campo-de-archivo
• Configuración:
  • Etiqueta
  • Requerido
  • Tipos de Archivo Permitidos (multiselección)
  • Tamaño Máximo de Archivo (MB)
  • Habilitar recorte de imágenes (solo para JPEG/PNG)
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo de editor (WYSIWYG)

• Tipo: campo-editor
• Configuración:
  • Etiqueta
  • Requerido
  • Contenido del editor (editor de texto enriquecido)
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo de titular

• Tipo: campo-titular
• Configuración:
  • Contenido de texto
  • Nivel de encabezado (H1-H6)
  • Alinear
  • Clase CSS
  • Nota: No tiene Opciones Avanzadas

Campo divisor

• Tipo: campo-divisor
• Configuración:
  • Estilo (sólido, discontinuo, punteado)
  • Ancho (porcentaje)
  • Alinear
  • Clase CSS
  • Nota: No tiene Opciones Avanzadas

Campo de imagen

• Tipo: campo-imagen
• Configuración:
  • Selección de imagen
  • Texto alternativo
  • URL del enlace (opcional)
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo HTML

• Tipo: campo-html
• Configuración:
  • Contenido HTML (editor de código)
  • Alinear
  • Clase CSS
  • Opciones Avanzadas

Campo de shortcode

• Tipo: campo-shortcode
• Configuración:
  • Contenido del shortcode
  • Alinear
  • Clase CSS
  • Nota: No tiene Opciones Avanzadas

Campo oculto

• Tipo: campo-oculto
• Configuración:
  • Nombre del campo
  • Valor predeterminado
  • Opciones Avanzadas
  • Nota: No tiene ajustes de Etiqueta, Marcador de posición, Requerido, Alineación o Clase CSS

Campos Pro

Estos campos están disponibles en Charitable Pro y aparecen en la categoría “Campos Pro”.

Campo de comentario del donante

• Tipo: campo-comentario-donante
• Configuración:
  • Etiqueta
  • Marcador de posición
  • Requerido
  • Filas (número de filas del área de texto)
  • Longitud Máxima (límite de caracteres)
  • Alinear
  • Clase CSS
  • Opciones Avanzadas
• Nota: Requiere que los comentarios del donante estén habilitados en la configuración de Charitable.

Campo de código de referencia

• Tipo: campo-codigo-referencia
• Configuración:
  • Etiqueta
  • Marcador de posición
  • Requerido
  • Alinear
  • Clase CSS
  • Opciones Avanzadas
• Nota: Requiere que las referencias de donantes estén habilitadas en la configuración de Charitable.

---

Opciones Avanzadas

Las opciones avanzadas están disponibles en la mayoría de los campos del formulario (con algunas excepciones mencionadas anteriormente). Estas opciones controlan cómo se manejan y muestran los datos del campo en varios contextos.

Mostrar en Exportación

Cuando esté habilitado, los datos de este campo se incluirán en las exportaciones e informes de donaciones. Esto es útil para campos que contienen información importante del donante que desea rastrear y analizar.

Detalles técnicos: Los datos del campo se almacenan en los metadatos de la donación y se incluyen cuando las funciones de exportación consultan los datos de la donación. El campo debe tener esta opción habilitada para que sus datos aparezcan en las exportaciones CSV y otras herramientas de informes.

Mostrar en Correo Electrónico

Cuando esté habilitado, se creará una etiqueta de correo electrónico para este campo que se puede usar en las plantillas de correo electrónico. El formato de la etiqueta suele ser {field_field_id} o una etiqueta personalizada basada en el nombre del campo.

Detalles técnicos: Las etiquetas de correo electrónico se registran en el sistema de correo electrónico de Charitable y se pueden usar en los correos electrónicos de recibo de donaciones, notificaciones administrativas y otras plantillas de correo electrónico. El valor del campo se formatea e inserta automáticamente cuando se envía el correo electrónico.

Mostrar en Metadatos

Cuando esté habilitado, los datos de este campo se mostrarán en la página de detalles de donaciones del administrador en la sección de metadatos de la donación. Esto permite a los administradores ver los datos de campos personalizados al revisar las donaciones.

Detalles técnicos: Los datos del campo se muestran en el cuadro de metadatos de la donación en la pantalla de edición de donaciones del administrador de WordPress. Esto proporciona una forma conveniente de ver todos los datos de campos personalizados asociados con una donación sin necesidad de exportar o consultar la base de datos.

Nota: Algunos campos (como el campo de comentarios del donante y el campo de código de referencia) tienen "Mostrar en Metadatos" habilitado por defecto y no se pueden deshabilitar, ya que esta información se considera esencial para los registros de donaciones.

---

Lógica Condicional

La lógica condicional te permite mostrar u ocultar campos basándose en los valores de otros campos. Esto crea formularios dinámicos e interactivos que se adaptan según la entrada del usuario.

Cómo funciona

La lógica condicional utiliza un sistema basado en reglas donde puedes:

1. Habilitar Lógica Condicional – Activar/desactivar la lógica condicional para cualquier campo
2. Establecer Tipo de Acción – Elegir "Mostrar" u "Ocultar" el campo cuando se cumplan las condiciones
3. Crear Reglas – Definir condiciones basadas en los valores de otros campos
4. Agrupar Reglas – Usar lógica Y/O para crear condiciones complejas

Estructura de Reglas

• Campo – Seleccionar qué campo comprobar
• Operador – Elegir el operador de comparación (igual, no igual, contiene, etc.)
• Valor – Introducir el valor con el que comparar

Grupos de Lógica

Las reglas se pueden agrupar usando:

• Y – Todas las reglas de un grupo deben ser verdaderas
• O – Cualquier regla de un grupo puede ser verdadera (grupos separados)

Implementación Técnica

La lógica condicional se evalúa en el frontend utilizando JavaScript. Las reglas se almacenan en la matriz conditionals del campo y en el indicador booleano conditional_logic. El sistema admite la evaluación en tiempo real a medida que los usuarios interactúan con el formulario.

Filtro: charitable_visual_form_conditional_logic_enabled – Se puede usar para deshabilitar la lógica condicional globalmente o para campos específicos.

---

Formularios de Múltiples Pasos

Los formularios de varios pasos le permiten dividir los formularios de donación en varias páginas o pasos, mejorando la experiencia del usuario para formularios más largos.

Tipos de Formulario

• Formulario de una sola página – Todos los campos en una página (predeterminado)
• Formulario de varios pasos – Campos divididos en varios pasos/diapositivas

Gestión de Pasos

• Pasos Mínimos: Se requieren 2 pasos para formularios de varios pasos
• Pasos Máximos: Se permiten 4 pasos
• Etiquetas de Paso: Cada paso puede tener una etiqueta personalizada
• Navegación de Pasos: Botones Anterior/Siguiente con texto personalizable
• Indicadores de Progreso: Los indicadores visuales de progreso muestran la finalización del formulario

Configuración de Pasos

Los pasos (también llamados “diapositivas”) se gestionan en el panel Opciones del Formulario. Puede:

• Añadir nuevos pasos
• Eliminar pasos (se requieren un mínimo de 2)
• Renombrar pasos
• Reordenar pasos
• Asignar campos a pasos específicos

Navegación

• Botón Anterior – Navegar al paso anterior (oculto en el primer paso)
• Botón Siguiente – Navegar al siguiente paso (valida el paso actual antes de continuar)
• Botón Enviar – Solo visible en el último paso
• Encabezados de Paso – Encabezados de paso opcionales y clicables para la navegación (se pueden deshabilitar)

Validación

Cada paso se valida antes de permitir la progresión al siguiente paso. Solo se validan los campos con los que se ha interactuado, lo que evita errores de validación prematuros.

Animación

Las transiciones de pasos se pueden animar. El tipo de animación se puede filtrar usando charitable_multistep_animation_type.

Filtros:

• charitable_multistep_prev_button_text – Personalizar el texto del botón “Anterior”
• charitable_multistep_prev_button_text – Personalizar el texto del botón “Siguiente”
• charitable_multistep_show_step_number – Controlar la visualización del número de paso
• charitable_multistep_step_label – Personalizar las etiquetas de los pasos

---

Validación de Campos

La validación de campos garantiza que los usuarios proporcionen información correcta y completa antes de enviar el formulario.

Tipos de validación

1. Validación de campo obligatorio – Asegura que los campos obligatorios no estén vacíos
2. Validación de formato – Valida el formato del campo (correo electrónico, URL, número, etc.)
3. Validación de rango – Valida los valores mínimo/máximo para campos numéricos y de fecha
4. Validación de archivo – Valida el tipo de archivo, tamaño y otras restricciones de carga
5. Validación personalizada – Reglas de validación específicas del campo

Momento de la validación

• Al enviar – La validación completa del formulario se realiza al hacer clic en el botón de envío
• Al avanzar de paso – Los formularios de varios pasos validan el paso actual antes de permitir el siguiente
• En tiempo real – Algunos campos pueden validarse mientras el usuario escribe (depende del navegador)

Acciones de validación

Cada tipo de campo tiene un método validate() que se llama a través de la acción charitable_form_process_validate_{field_type}. Los errores de validación se muestran a los usuarios y evitan el envío del formulario hasta que se resuelvan.

Visualización de errores

Los errores de validación se muestran:

• Debajo del campo que falló la validación
• En un resumen en la parte superior del formulario (si hay varios errores)
• Con mensajes de error claros y fáciles de entender

---

Renderizado en el Frontend

El generador de formularios visual utiliza un sistema de renderizado especializado que convierte los datos de los campos del generador en formularios HTML funcionales en el frontend.

Proceso de renderizado

1. Recuperación de datos del formulario – La configuración del formulario se carga desde los metadatos de la publicación de la campaña
2. Registro de campos – Los campos se registran en la API de Campos de Donación de Charitable
3. Renderizado de plantillas – Los campos se renderizan utilizando plantillas adaptadas al tema
4. Aplicación de estilos – Las clases CSS y los estilos en línea se aplican según la configuración del formulario
5. Inicialización de JavaScript – El JavaScript del frontend maneja las interacciones y la validación

Clases de renderizado

Los formularios reciben clases CSS basadas en:

• Tipo de formulario (una página o varios pasos)
• Selección de tema
• Ajustes de densidad
• Clases CSS personalizadas

Contenedores de campos

Cada campo está envuelto en contenedores que proporcionan:

• Espaciado y diseño consistentes
• Soporte de alineación
• Comportamiento adaptable
• Integración de temas

Renderizado de varios pasos

Los formularios de varios pasos se renderizan con:

• Contenedores de pasos que se muestran/ocultan según el paso actual
• Controles de navegación
• Indicadores de progreso
• Validación específica del paso

---

Integración de Temas

El generador visual de formularios incluye una sofisticada integración de temas que adapta automáticamente los formularios para que coincidan con los estilos de su tema de WordPress activo o de su maquetador de páginas.

Detección de temas

El sistema detecta automáticamente:

• Tema activo de WordPress
• Estilos del maquetador de páginas Elementor (si está activo)
• Esquemas de color y tipografía del tema

Herencia de estilos

Los formularios pueden heredar estilos de:

• Temas de WordPress – Detecta y aplica automáticamente colores, fuentes y espaciado del tema
• Elementor – Hereda los colores globales y la configuración de tipografía de Elementor
• Variables CSS personalizadas – Utiliza propiedades personalizadas de CSS para una fácil tematización

Variables CSS

Los formularios utilizan propiedades personalizadas de CSS (variables) para el estilo, lo que permite una fácil personalización:

• --charitable-field-gap – Espaciado entre campos
• --charitable-input-padding-y – Relleno vertical para los campos de entrada
• --charitable-input-padding-x – Relleno horizontal para los campos de entrada
• --charitable-input-border-color – Color del borde de los campos de entrada
• --charitable-input-border-radius – Radio del borde de los campos de entrada
• --charitable-focus-ring-color – Color del anillo de enfoque
• Y más…

Clases de tema

Los formularios reciben clases CSS específicas del tema que permiten a los desarrolladores de temas aplicar estilos personalizados a los formularios:

• Clases de densidad (base, espaciado)
• Clases específicas del tema
• Clases de tipo de formulario (único, varios pasos)

Para desarrolladores de temas

Para personalizar los formularios visuales en tu tema:

1. Usa variables CSS – Anula las propiedades personalizadas de CSS en tu hoja de estilos del tema
2. Aplica clases de tema – Usa las clases del tema aplicadas a los formularios para estilos específicos
3. Usa filtros – Engancha los filtros de detección de temas para personalizar la herencia de estilos
4. Clases CSS personalizadas – Añade clases CSS personalizadas a los campos a través de la configuración de Clase CSS

Filtros para integración de temas

• charitable_visual_form_theme_classes – Modifica las clases del tema
• charitable_visual_form_theme_variables – Personaliza las variables CSS
• charitable_visual_form_enable_theme_inheritance – Habilita/deshabilita la herencia de temas
• charitable_visual_form_detected_theme_styles – Modifica los estilos de tema detectados
• charitable_visual_form_theme_style_map – Personaliza el mapeo de estilos
• charitable_visual_form_theme_fallback – Proporciona valores de reserva

Para diseñadores

El generador de formularios visuales proporciona:

• Estilo Consistente – Los formularios coinciden automáticamente con el diseño de tu sitio
• Diseño Adaptable – Los formularios se adaptan a diferentes tamaños de pantalla
• Accesibilidad – Los formularios siguen las mejores prácticas de accesibilidad
• Opciones de Personalización – Ajustes fáciles de usar para colores, espaciado y diseño

Temas de densidad

Hay dos opciones de densidad disponibles:

• Base – Espaciado estándar (predeterminado)
• Espaciado – Espaciado aumentado para una mejor legibilidad

La densidad afecta a los huecos de los campos, al relleno de las entradas y al espaciado general del formulario.

---

Duplicación de Campos

Los campos se pueden duplicar para crear rápidamente campos similares con la misma configuración.

Proceso de duplicación

1. Haz clic en el icono de duplicar de cualquier campo
2. Elige el modo de duplicación:
   • Copiar configuración – Duplica el campo con toda la configuración (excepto la lógica condicional y las opciones avanzadas)
   • Usar valores predeterminados – Crea un nuevo campo con la configuración predeterminada pero conserva la etiqueta original (con “(Copia)” añadido)

Qué se duplica

Al copiar la configuración:

• Etiqueta del campo (con “(Copia)” añadido si no está ya presente)
• Tipo de campo
• Toda la configuración específica del campo (opciones, marcadores de posición, etc.)
• Estado de requerido
• Alineación
• Clases CSS
• Valores predeterminados

Qué NO se duplica

• Lógica condicional (siempre se restablece)
• Opciones avanzadas (siempre se restablecen)
• ID del campo (se asigna un nuevo ID único)

Gestión de ID de campo

Cada campo duplicado recibe un ID de campo nuevo y único. El sistema utiliza transitorios para rastrear el próximo ID de campo disponible y evitar conflictos.

---

Límites y Restricciones de Campos

Ciertos campos tienen restricciones sobre cuántas veces se pueden agregar a un formulario.

Campos con límites

Los siguientes campos solo se pueden agregar una vez por formulario:

• Campos de nombre del donante (max_allowed: 1)
• Campo de correo electrónico del donante (max_allowed: 1)
• Campos de dirección (max_allowed: 1)
• Política de privacidad (max_allowed: 1)
• Donaciones (max_allowed: 1)
• Sección de Pago (max_allowed: 1)

Campos que no se pueden duplicar

Algunos campos no se pueden duplicar incluso si no tienen un límite estricto:

• Todos los campos requeridos listados arriba
• Sección de pago

Límites del formulario de varios pasos

• Pasos Mínimos: Se requieren 2 pasos para formularios de varios pasos
• Pasos Máximos: Se permiten 4 pasos

Disponibilidad de campos

Algunos campos requieren configuraciones específicas para ser habilitados:

• Campo de Comentario del Donante – Requiere que los comentarios del donante estén habilitados en Charitable → Configuración → Donantes
• Campo de Código de Referencia – Requiere que las referencias de donantes estén habilitadas en Charitable → Configuración → Donantes

Estos campos se deshabilitarán en el constructor si no están habilitadas las configuraciones requeridas, con una ventana modal que explica cómo habilitarlos.

---

Limitación de entrada de donaciones del administrador

Importante: Al agregar manualmente una donación en el administrador de WordPress (a través de Donaciones → Agregar Nueva), los campos personalizados del constructor de formularios visuales no son compatibles ni se muestran.

Solo las donaciones enviadas a través del formulario frontal capturarán y almacenarán datos de campos personalizados. Las donaciones creadas por el administrador no tendrán acceso a:

• Campos de formulario personalizados agregados a través del constructor visual
• Validación específica de campos
• Almacenamiento de datos de campos personalizados
• Configuraciones de opciones avanzadas

Esta limitación existe porque la interfaz de entrada de donaciones del administrador utiliza el formulario de donación estándar de Charitable, no el sistema de constructor de formularios visuales. Los campos personalizados creados en el constructor visual solo se procesan y almacenan cuando las donaciones se envían a través del formulario frontal.

---

Recursos adicionales

Para obtener más información sobre cómo extender el constructor de formularios visuales:

• Documentación para desarrolladores de Charitable
• Documentación de ganchos y filtros de WordPress
• Repositorio de GitHub de Charitable

---

Versión del documento: 1.0 Última actualización: 28 de noviembre de 2025