Los widgets

Todo lo que se ve en una pantalla es un widget. La paleta Widgets, a la izquierda del canvas, trae 32 widgets de origen — de esta página sales sabiendo para qué sirve cada uno, y con los principales explicados al detalle. Si la app tiene widgets programados por ti, aparecen en la misma paleta, en la sección Custom.

#El catálogo, por categoría

#Campos de formulario

Todos se conectan a un campo de un datastore de registro (sección Conexión a datos) y entran en la validación — ver los formularios.

Widget	Para qué sirve
Caja de texto	Texto de una línea. Tiene Máscara, modo Password (ocultar el texto) y placeholder.
Área de texto	Texto largo, multilínea — notas, descripciones.
Número	Valores numéricos.
Sí/No	Un interruptor booleano.
Lista	Elección de opciones: Lista fija, Enum del modelo o Datastore; con Buscable, Multiselección y modo Árbol (jerárquica).
Fecha	Fecha, Fecha y hora o solo Hora (el campo Tipo decide).
Color	Elección de un color.
Archivo	Subida por arrastre y/o botón, con previsualización, límite de tamaño y elección del almacenamiento. El límite nunca pasa del Archivo máximo (MB) de la configuración de la plataforma, hasta 100 MB. Con En el propio campo (base64), el archivo va dentro de la petición y el límite es de unos 3 MB. Cada cuenta envía hasta 300 archivos y 3 GB por hora (y cada dirección hasta 20 GB); por encima, el widget dice que se enviaron demasiados archivos y pide intentarlo más tarde.

Todos los campos con valor muestran una × discreta a la derecha que lo limpia — en una Lista usada como filtro es la forma de volver a "todos" sin elegir nada. La Lista simple abre las opciones bajo el campo; con Con búsqueda abre una caja de búsqueda y la lista se acorta al escribir; con Selección múltiple cada opción se activa y desactiva con una marca.

La Lista muestra 10 opciones a la vez. La propiedad Opciones visibles, en Comportamiento, cambia ese número (0 las muestra todas). Cuando hay más opciones que ese número, la lista incluye un cuadro de búsqueda, incluso sin Con búsqueda, y un pie con el total, por ejemplo «10 de 245 · escribe para buscar». La búsqueda recorre todas las opciones e ignora acentos y mayúsculas. En una Multiselección, las opciones ya elegidas aparecen primero en la lista, y el campo muestra las dos primeras seguidas de «+N».

En el pie, la lupa (Ver todo) abre una ventana con todas las opciones en una tabla, con búsqueda y 50 filas por página. Con el Origen de opciones en Datastore, las Columnas de la ventana de selección añaden campos junto a la etiqueta (por ejemplo, el NIF, para distinguir dos clientes con el mismo nombre), y la ventana incluye una barra de filtros sobre esos campos. En una elección simple, hacer clic en una fila elige la opción. En una Multiselección, cada fila tiene una casilla, Marcar todos marca los resultados de todas las páginas, y solo Aplicar guarda la elección; Cancelar no cambia nada. La ventana mantiene siempre el mismo tamaño, con pocos o muchos resultados.

En KeplinGo, la Lista abre una hoja con la misma regla: 10 opciones, búsqueda y el pie con el total. Ver todo muestra todas las opciones en la misma hoja, con los campos de las Columnas de la ventana de selección debajo de cada etiqueta, y la Multiselección solo guarda con Aplicar.

Con la Carga del datastore de la Lista en Una página cada vez, solo la primera página llega a la pantalla. La búsqueda pregunta entonces al servidor, el total del pie es el del servidor, la ventana de selección pide cada página al servidor, y el campo obtiene del servidor el nombre de un valor guardado que la primera página no trajo. En este modo, la búsqueda busca en la etiqueta (que debe ser un campo de texto), las mayúsculas y los acentos cuentan como los cuenta la base de datos, y Marcar todos no aparece, porque obligaría a traer todos los registros.

#Acciones y navegación

Widget	Para qué sirve
Botón	La acción clásica. Mostrar: Icono + Texto, Solo icono o Solo texto; la Acción al hacer clic navega, abre un modal o ejecuta código.
Botón con menú	Un botón que abre más opciones. Apariencia: Dividido (el cuerpo actúa, la flecha abre el menú), Menú o Hamburguesa. Cada opción puede ocultarse o desactivarse por condiciones.
Enlace	Texto clicable — Destino: Pantalla de la app (con parámetros) o URL externa (con Abrir en pestaña nueva).
Breadcrumb	El camino «estás aquí», con niveles clicables y el último nivel fijo o conectado a un campo.
Exportar	Un botón que descarga los datos de un datastore en hoja de cálculo (.xlsx) — campos elegidos, Fila de cabecera opcional y Nombre del archivo con {date}.

Exportar lee los datos en el momento del clic, por bloques, hasta 50 000 filas; por encima de eso, el archivo sale con las primeras 50 000 y aparece un aviso. El evento onExport dice si el archivo se recortó (truncated).

En KeplinGo el archivo sale en CSV; un texto que Excel leería como fórmula (que empiece por = o @, por ejemplo) lleva un apóstrofo delante.

#Estructura

Widget	Para qué sirve
Panel	Un contenedor con marco y título — ordena widgets que pasan a moverse en conjunto.
Pestañas	Un contenedor con pestañas; cada widget hijo pertenece a una pestaña. Estilo de las pestañas: Caja, Píldoras o Subrayado.
Barra fija	Una barra a todo el ancho, fijada Arriba o al Pie de la pantalla — para barras de acciones siempre visibles.
Línea	Una línea separadora, Horizontal o Vertical — el color y el trazo vienen de la Apariencia.

#Contenido y media

Widget	Para qué sirve
Etiqueta	Texto simple — títulos, leyendas, valores sueltos. Acepta Valores de la frase ({n} en el texto).
Markdown	Texto rico escrito en Markdown — fijo o venido de un campo.
Imagen	Una imagen por URL fija, Asset de la app o Campo (dinámico); Ajuste: Contener, Rellenar o Estirar.
Página externa	Incrusta una página de fuera (un mapa, un vídeo, BI de terceros) o HTML escrito por ti. Corre aislada: no ve la sesión ni los datos de la app.

#Datos

Widget	Para qué sirve
Tabla	La cuadrícula de registros — columnas tipadas, ordenación, selección y botones de acción. Detalle abajo.
Lista	Registros en lista vertical, con campos en papeles (Título, Subtítulo, Cuerpo, Leyenda) e imagen opcional.
Tarjetas	La misma plantilla de la Lista, pero en cuadrícula de tarjetas con N Columnas.
Gráfico	Series dibujadas — barras, líneas, tartas y más. Detalle abajo.
KPI	Una franja de indicadores numéricos con tendencias, objetivo y sparkline. Detalle abajo.
Barra de filtros	Condiciones en chips (campo, operador, valor) que filtran una Tabla, Lista, Tarjetas, Kanban o Gráfico de la pantalla. Detalle abajo.

#Tableros y planificación

Widget	Para qué sirve
Kanban	Tarjetas arrastrables entre columnas de estado. Detalle abajo.
Calendario	Eventos en vistas Día/Semana/Mes/Año. Detalle abajo.
Gantt	Barras de inicio→fin con progreso, grupos y dependencias. Detalle abajo.

#Documentos y procesos

Widget	Para qué sirve
Informe	Muestra un informe de la app (PDF) dentro de la pantalla, con parámetros conectados a lo que hay en pantalla y Barra de acciones para actualizar y descargar.
Estado del proceso	El historial y el paso actual de los workflows de un registro, con botones de decisión cuando la tarea abierta es de quien está mirando.
Mis tareas	La bandeja de entrada de tareas de workflow del usuario con sesión — abre la pantalla de la tarea y decide desde ahí.

#La Tabla

La Tabla es el widget más usado de la plataforma: se conecta a un datastore de lista y muestra los registros en cuadrícula, con paginación, ordenación y selección.

El pie con el total y las flechas de página solo aparece cuando los registros no caben en una página. Lo mismo vale para los widgets Lista y Tarjetas.

Las fechas que vienen de la API se muestran en el idioma de la app, y una columna solo de día muestra solo el día.

#Columnas

Al conectar el datastore, las columnas nacen una por campo. Después afinas: en Columnas, usa + columna para añadir, y haz clic en una columna en el canvas para editarla — el inspector cambia a ella.

Cada columna tiene Cabecera, Ancho, Ordenable por la cabecera, Oculta — y un Tipo:

Tipo	Qué hace
Texto	El valor tal cual, con Máscara opcional (# = carácter).
Número	Formatea el valor: Número (regional) (con Decimales, Separador de miles, Compacto — 1,2 M en vez de 1 234 567 —, Prefijo y Sufijo) o Máscara (# = dígito).
Enlace	La celda queda clicable. Destino: Pantalla de la app (con parámetros venidos de Campo de la fila, Parámetro de la URL o Valor fijo) o Script — código tuyo corriendo en el clic. Es la columna adecuada para abrir la ficha de un registro desde la lista: la columna que identifica la fila (nombre, descripción, fecha) lleva a la pantalla de la ficha con el id de la fila; una pantalla en modo modal o panel lateral se abre encima y, al cerrarse, la lista se recarga.
Imagen	Muestra la imagen cuya dirección/contenido está en el campo.
Archivo	Un enlace de descarga al archivo referido en el campo.
Gráfico spark	Un gráfico pequeño por fila, en Líneas o Barras, sin ejes ni etiquetas. La serie viene de un Campo con lista (una lista de números en JSON o de la API, o un texto como 3,5,4) o de Varios campos de la fila, un punto por campo. Puedes elegir el Color, Mostrar último valor al lado y una Escala fija (mínimo y máximo) para comparar filas entre sí. Esta columna no ordena desde la cabecera.

Una columna de un campo de relación (cliente.nombre) no ordena por la cabecera: la ordenación corre en el servidor, que solo conoce los campos de la propia tabla.

#Acciones de la tabla

En la categoría Comportamiento, la sección de acciones crea los botones CRUD: Refrescar, Añadir nuevo, Editar registro, Quitar registro y Quitar múltiples. Cada acción activada crea un botón suelto en el canvas, conectado a la tabla — posicionas y estilizas ese botón como cualquier otro.

• Añadir nuevo y Editar registro abren una pantalla o un modal a tu elección (típicamente el formulario del registro), con los parámetros rellenados a partir de la fila.
• Editar registro y Quitar registro solo se activan con una fila seleccionada; Quitar múltiples trabaja sobre la Selección múltiple (el interruptor que añade la columna de checkboxes).
• Las acciones que escriben exigen que el datastore tenga clave primaria — el inspector avisa: El datastore necesita una clave primaria.

#Formularios (inputs + registro + validación)

No hay un widget «formulario»: un formulario es la suma de tres piezas, y es esa libertad la que te deja diseñar la ficha como quieras.

1. Crea un datastore de registro en la pantalla (ver Datastores y datos) — por ejemplo, conta, cargado por la clave venida del parámetro id de la ruta.
2. Arrastra los campos de formulario (Caja de texto, Lista, Fecha…) y, en cada uno, conecta la Conexión a datos al campo correcto del datastore.
3. Pon un Botón «Guardar» cuyo evento guarda el datastore — la acción predefinida Guardar datastore del editor de eventos escribe el código por ti (ver Eventos y el SDK).

La validación vive en cada campo, en la categoría Validación:

• Obligatorio — el campo tiene que venir relleno.
• Las reglas estándar: Mín. caracteres, Máx. caracteres, Es email, Es teléfono, Es número, Valor mín., Valor máx., Patrón (regex) e Igual al campo (confirmación de contraseña, por ejemplo).
• Validación con script — para lógica tuya: el código recibe value (el valor actual del campo) y devuelve true si es válido, o el mensaje de error. Un NIF, un IBAN, una regla de negocio.

Al guardar, la validación corre entera: obligatorios primero, luego las reglas, luego el script. El registro solo sigue si todo pasa.

Un campo con error queda con el borde rojo, y el mensaje aparece debajo de él, en el espacio entre widgets. El campo y la etiqueta no cambian de sitio. Para que el mensaje se vea entero, deja al menos 16 píxeles entre un campo y el widget de abajo, y entre un campo y el fondo del panel o la pestaña que lo contiene.

#El Gráfico

El Gráfico se conecta a un datastore y dibuja series. En Tipo de gráfico eliges: Barras, Línea, Área, Tarta / Donut, Dispersión, Radar, Gauge (medidor), Embudo o Mapa de calor.

Lo esencial es el mapeo, en la categoría Datos:

• Campo de categoría (eje X / porciones) — lo que separa las barras/porciones.
• Campos de valor — uno o más campos numéricos; cada uno es una serie.
• Campo de serie (agrupación) — como alternativa a los varios valores: pivota por el primer campo de valor y crea una serie por valor distinto (sin valores, cuenta registros).

Y después el acabado:

Opción	Qué hace
Apilado, Horizontal, Líneas suaves, Valores en los puntos	Variaciones del dibujo, según el tipo.
Leyenda, Posición de la leyenda, Tooltip	El chrome del gráfico. La leyenda también se arrastra directamente en el gráfico para posicionarla.
Formato de los valores	El mismo formato de las columnas Número de la tabla, aplicado a ejes, etiquetas y tooltip.
Escala de los valores	Lineal o Logarítmica — la logarítmica sirve cuando las series tienen órdenes de magnitud distintos.
Usar un segundo eje	Un eje a la derecha con escala propia — para juntar un total en euros y un recuento en el mismo gráfico.
Series	Tipo por serie (combos de barras con líneas) y qué series van al 2.º eje.
Opciones avanzadas	Un editor de código con todas las propiedades del motor de gráficos, con autocompletado — aplicadas por encima de la configuración, para los casos que los campos no cubren.

#El KPI

El KPI es una franja de indicadores — cuatro números lado a lado se hacen con un widget de cuatro indicadores, no con cuatro widgets: la alineación y el espaciado quedan garantizados.

Cada indicador (en Indicadores ▸ Añadir indicador) tiene:

• Rótulo e icono, con Posición de la leyenda (Encima del valor / Debajo del valor).
• Valor (campo) + Agregación (Suma, Media, Recuento, Máximo, Mínimo, Primero, Último) sobre el conjunto de datos — o un Valor manual cuando no hay datos conectados.
• Tendencias (Añadir tendencia) — comparaciones bajo el número, con Campo de referencia, formato Porcentaje o Valor absoluto, y Menos es mejor (invierte los colores): en una deuda creciendo, la flecha tiene que ser roja.
• Objetivo — Sin objetivo, Valor manual o Campo del datasource, con Barra de progreso opcional.
• Mostrar sparkline — la minilínea del histórico, con Campo de la serie.
• Período (del campo) — de qué cierre habla el número (una fecha ISO se muestra como MM/AAAA).

El conjunto de datos es compartido por el widget, pero cada indicador puede tener un Conjunto de datos propio.

#El Kanban

El Kanban muestra los registros como tarjetas en columnas — el pipeline de oportunidades de la Gestión de Clientes es un kanban por estado.

1. Conecta el datastore y elige el Campo de estado (columna) — el campo que dice en qué columna está cada tarjeta.
2. Define la Fuente de las columnas: Estática (añades cada columna con Etiqueta, Valor y color) o Enum (las columnas vienen de los valores de un enum del modelo).
3. Compón la Plantilla de la tarjeta — los campos y papeles, como en la Lista.

Con Permitir arrastrar tarjetas activado, mover una tarjeta guarda enseguida el nuevo estado en el registro. Campo de orden (un campo numérico) hace persistente la ordenación dentro de la columna. Columna para sin categoría atrapa los registros cuyo estado no coincide con ninguna columna; Recuento de tarjetas muestra el total en la cabecera.

Las acciones: Clic en una tarjeta (editar) y Crear tarjeta (botón en la columna) — cada una puede navegar a una pantalla, abrir un modal (con los parámetros de la fila y de la columna) o emitir un evento para código tuyo.

#El Calendario

El Calendario muestra registros con fecha como eventos, en las vistas Día, Semana, Mes y Año.

• Campos: Campo de fecha (inicio), Campo de fin (opcional) (eventos multidía), Campo de título.
• Color de los eventos: Único o Por campo — con un mapa valor → color (un enum de tipo, por ejemplo).
• Vista: Vista inicial, Vistas disponibles, 1.er día de la semana (Lunes/Domingo), Máx. eventos por día en la vista mes, horas de Inicio/Fin en las vistas de día/semana, Barra de navegación y Botones de cambio de vista.
• Acciones: Clic en un evento (editar) y Selección de día/intervalo (crear) — el inicio/fin siguen hacia la pantalla de destino como parámetros, listos para prerrellenar el formulario de creación.

El calendario solo carga los registros del intervalo visible — cambiar de mes va a buscar el mes nuevo, no la tabla entera.

#El Gantt

El Gantt dibuja barras de inicio→fin en una línea temporal — planificación de proyectos, campañas, onboarding de clientes.

• Campos: Campo de inicio, Campo de fin, Campo del rótulo, Campo de progreso (0–100) y Campo de grupo (agrupa filas).
• Campo de dependencias — los IDs (clave primaria) de los predecesores, en lista JSON o separados por comas; el Gantt dibuja las flechas.
• Zoom inicial (Día, Semana, Mes), Línea de hoy y Sombrear fines de semana.
• Acciones: Clic en una barra (editar) y Clic en espacio vacío (crear) — la fecha clicada sigue como parámetro.

El Gantt es de lectura: las barras no se arrastran — las fechas se cambian en el formulario del registro.

#La Barra de filtros

La Barra de filtros permite a quien usa la app filtrar una lista por cualquier campo, sin que tengas que dibujar un campo de filtro por cada columna. Se coloca sobre una Tabla, Lista, Tarjetas, Kanban o Gráfico y escribe las condiciones en chips.

1. Arrastra la Barra de filtros a la pantalla y, en Datos, elige el Widget objetivo — el widget de listado cuyo datastore recibe las condiciones.
2. En Campos filtrables, elige los campos a ofrecer. Sin elección, la barra ofrece todos los campos simples del datastore del objetivo; las cabeceras de las columnas de la tabla sirven de etiqueta. Los campos de relación (cliente.nombre) no se ofrecen: el filtro corre en el servidor, que solo conoce los campos de la propia tabla.
3. Opcional: en Valores visibles, elige cuántos valores sugeridos muestra la lista a la vez (10 por defecto; 0 los muestra todos). La búsqueda recorre siempre todos los valores, y un pie indica cuántos hay. En el paso del valor, la lupa del pie abre la ventana de selección con todos los valores del campo.

En la app, cada condición se escribe en tres pasos, siempre a la vista: el campo, el operador y el valor. Las opciones del paso siguiente aparecen solas; escribir las filtra. Los valores sugeridos salen de los datos cargados, pero lo que se escribe vale siempre, aunque no esté en la lista.

Los operadores dependen del tipo del campo: texto (contiene, igual a, empieza por…), número y fecha (comparaciones), y listas (igual a, distinto de). Cualquiera de y ninguno de aceptan varios valores en el mismo chip: cada elección entra, y Intro o Aplicar cierra la condición. La × de un chip quita esa condición; la × de la barra lo limpia todo.

Cuando una condición se cierra, la lista no vuelve a abrirse sola: la barra queda lista para escribir. Para otro filtro, escribe, haz clic en la barra o pulsa ↓.

Las condiciones se suman a las del datastore del objetivo (Filtros (where)) y la petición va al servidor con paginación — filtrar no trae la tabla entera. Los filtros por widget (una Lista vinculada a una condición del datastore) siguen existiendo y pueden convivir en la misma pantalla: el desplegable rápido para el filtro más usado, la barra para todo lo demás.

En los campos de fecha, el valor se escribe como se lee: «26/09/2026», «26-09-2026», «26.09.2026» o «2026-09-26», con o sin hora. Cuando el día y el mes se pueden confundir, el día va primero. Una fecha sin hora vale por el día entero: menor o igual a 26/09/2026 incluye los registros de ese día, y mayor que 26/09/2026 empieza al día siguiente. Distinto de y ninguno de incluyen los registros con el campo vacío.

#¿Por qué no…?

• ¿Por qué no aparece la sección Validación en mi widget? Solo los campos de formulario validan — un Botón o una Etiqueta no tienen valor que validar.
• ¿Por qué el widget aparece en la paleta pero gris en el canvas? Está desactivado (interruptor Activo en la categoría Layout) o una regla/evento lo desactivó.
• ¿Por qué no veo datos en el canvas? El canvas muestra muestras — los datos reales aparecen en la previsualización y en la app publicada. Confirma la conexión en el capítulo Datastores y datos.
• ¿Por qué la Barra de filtros dice "Sin widget objetivo"? Falta elegir el Widget objetivo en Datos — solo los widgets con datastore de lista (Tabla, Lista, Tarjetas, Kanban, Gráfico) sirven de objetivo.