Las pantallas

Esta es la etapa más larga de la guía, y la que da cara a la app. Al final tienes cuatro pantallas diseñadas y funcionando sobre los datos reales del modelo: un Início con indicadores y un gráfico, una lista de Contas, una Ficha de Conta que guarda, y un tablero de Oportunidades con tarjetas arrastrables.

Antes de las pantallas, sin embargo, hay un paso corto que las hace posibles.

#Primero las APIs de tabla

Una pantalla no habla con la base de datos. Habla con datastores — los contenedores de datos de cada pantalla — y los datastores leen y escriben a través de las APIs de tabla de la app. Una API de tabla apunta a una entidad del modelo y genera, sola, las operaciones de lectura y escritura.

Vamos a crear tres, una por entidad:

1. Elige el panel Código en la barra lateral.
2. En la fila APIs, haz clic en el + (Nueva API).
3. En Nombre, escribe contas. El nombre es la base de las operaciones (getContas, addContas, updateContas, deleteContas) — por eso no le pongas prefijos como get o listar.
4. Haz clic en Crear API. El constructor se abre en la pestaña Construir.
5. En la sección Pipeline, elige el bloque Tabla.
6. En el campo Tabla, elige Dados CRM ▸ Contas.
7. En Acciones expuestas, deja Select, Insert, Update y Delete marcados — el CRM necesita los cuatro.
8. Deja Acceso público (sin sesión) todo desactivado: esta app es para quien tiene sesión iniciada.
9. En Campos incluidos, confirma que están marcados los campos que las pantallas van a usar. Para las cuentas, son todos.
10. Activa el interruptor Publicada y haz clic en Guardar.

Repite para las otras dos:

API	Entidad	Acciones	Notas
contas	Contas	Select, Insert, Update, Delete	Todos los campos.
contactos	Contactos	Select, Insert, Update, Delete	Incluye el navigator conta (solo el campo nome).
oportunidades	Oportunidades	Select, Insert, Update, Delete	Incluye el navigator conta (solo el campo nome).

Los navigators son lo que permite mostrar el nombre de la cuenta al lado de una oportunidad sin escribir una línea de SQL: márcalos en la lista de campos incluidos, y el campo conta.nome pasa a estar disponible en las pantallas.

#Crear las cuatro pantallas

Las pantallas viven en el panel UI, en la sección Pantallas.

1. Elige el panel UI en la barra lateral.
2. En la fila Pantallas, haz clic en el botón Nueva pantalla.
3. Escribe el nombre y confirma en Crear. La pantalla se abre enseguida en el espacio de trabajo.

Crea las cuatro de una vez, en este orden:

Nombre de la pantalla	Ruta	Qué va a ser
Início	/inicio	El panel comercial, con indicadores y gráfico.
Contas	/contas	La lista de cuentas.
Ficha de Conta	/ficha-de-conta	El formulario de una cuenta.
Oportunidades	/oportunidades	El tablero kanban.

La Ruta se deriva del nombre y se ve (y se edita) en el inspector, cuando ningún widget está seleccionado. Déjalas como están — la guía se refiere a ellas más adelante.

#La pantalla Início — el panel comercial

Abre la pantalla Início. El diseño tiene cuatro piezas: un título, una franja de indicadores, un gráfico y una tabla.

#El título

1. Arrastra una Etiqueta de la paleta a la parte superior del canvas.
2. En la categoría Contenido del inspector, escribe el texto Painel comercial.
3. En la categoría Apariencia, sube el Tamaño del texto — es el título de la página.

#La franja de indicadores

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

1. Arrastra un KPI bajo el título y estíralo a todo el ancho.
2. En la categoría Datos, la sección Indicadores empieza con uno. Usa Añadir indicador hasta tener cuatro.
3. Cada indicador tiene un Rótulo, un icono, un Conjunto de datos propio (su datastore) y un valor con Agregación.

Configúralos así:

Rótulo	Datastore (API de tabla)	Filtro	Valor
Contas ativas	contas	—	Recuento de id
Oportunidades abertas	oportunidades	fase ≠ fechada_ganha y fase ≠ fechada_perdida	Recuento de id
Valor em pipeline	oportunidades	el mismo filtro	Suma de valor
Fechado este trimestre	oportunidades	fase = fechada_ganha	Suma de valor

En los dos indicadores de dinero, abre el Formato y elige moneda EUR con cero decimales — 475.850 se lee mejor que 475850.

#El gráfico

1. Arrastra un Gráfico a la mitad izquierda, bajo el KPI.
2. En la categoría Datos, crea el datastore de lista sobre la API oportunidades.
3. En Tipo de gráfico, elige Barras.
4. En Campo de categoría (eje X / porciones), elige fase.
5. En Campos de valor, añade valor.
6. En la categoría Apariencia, activa Mostrar título y escribe Pipeline por fase.

#La tabla de próximos cierres

1. Arrastra una Tabla a la mitad derecha, junto al gráfico.
2. En la categoría Datos, crea el datastore de lista sobre oportunidades, con el filtro de las fases abiertas (el mismo de los indicadores), ordenado por data_fecho ascendente y Por página a
3. En la categoría Datos, sección Columnas, define cuatro columnas:

Campo	Cabecera
titulo	Oportunidade
conta.nome	Conta
valor	Valor (€)
data_fecho	Fecho

4. Activa Mostrar título y escribe Próximos fechos.

#La pantalla Contas — la lista

Abre la pantalla Contas. Son tres widgets.

1. Una Etiqueta arriba, con el texto Contas.
2. Un Botón en la esquina superior derecha: en la categoría Contenido, texto Nova conta e icono plus.
3. Una Tabla ocupando el resto de la pantalla. En la categoría Datos, crea el datastore de lista sobre la API contas, ordenado por nome ascendente, y define las columnas:

Campo	Cabecera
nome	Nome
sector	Sector
cidade	Cidade
telefone	Telefone
email	Email
estado	Estado

Falta conectar los dos gestos que hacen que esta lista sirva para algo. Ambos se escriben en la categoría Eventos, en TypeScript:

En el Botón, en el evento onClick — abrir la ficha en blanco, para crear:

keplin.nav.go("/ficha-de-conta");

En la Tabla, en el evento onRowClick — abrir la ficha de la fila clicada:

keplin.nav.go("/ficha-de-conta/" + keplin.event.row.id);

#La pantalla Ficha de Conta — el formulario

Esta es la pantalla con más piezas, y la que mejor muestra cómo funcionan los datos. Abre la pantalla Ficha de Conta.

#El parámetro de la ruta

1. Haz clic en una zona vacía del canvas — el inspector pasa a mostrar la pantalla.
2. En la sección Parámetros de ruta, haz clic en + añadir parámetro y escribe id.
3. Deja Obligatorio desactivado. Esto es deliberado: sin id la pantalla se abre en blanco, y así es como el mismo formulario sirve para crear una cuenta nueva.

La Ruta pasa a ser /ficha-de-conta/:id.

#Los dos datastores de la pantalla

Aún con la pantalla seleccionada, en la categoría Datos:

1. Haz clic en + registro. Haz clic en el datastore creado para abrir el modal Configurar datastore.
2. En Nombre del datastore, escribe conta.
3. En API, elige contas.
4. En Qué registro cargar (clave), haz clic en + campo de la clave y monta la condición: campo id, operador eq, valor Param ▸ id.
5. Deja Cargar automáticamente activado y cierra en Hecho.

Ahora el segundo, para los contactos de la cuenta:

1. Haz clic en + lista y ábrelo.
2. Nombre contactosConta, API contactos.
3. En Filtros (where), añade: campo conta_id, operador eq, valor Param ▸ id.
4. Ordena por nome ascendente.

#El formulario

1. Arrastra un Panel a la izquierda del canvas. En la categoría Apariencia, activa Mostrar título y escribe Dados da empresa.
2. Arrastra las Cajas de texto dentro del panel — soltar un widget dentro de un panel lo convierte en hijo suyo. Para cada una, en la categoría Contenido escribe la etiqueta y, en la categoría Datos, sección Conexión a datos, elige el datastore conta y el campo:

Etiqueta	Campo	Obligatorio
Nome	nome	sí
NIF	nif	no
Sector	sector	no
Cidade	cidade	no
Telefone	telefone	no
Email	email	no

3. Para el estado, usa una Lista en vez de una caja de texto: etiqueta Estado, conectada a conta ▸ estado, Obligatorio activado, y opciones estáticas:

Valor	Etiqueta
ativo	Ativo
prospeto	Prospeto
inativo	Inativo

4. Arrastra una Tabla a la derecha del panel, conectada al datastore contactosConta, con las columnas nome (Nome), cargo (Cargo) y telefone (Telefone), y el título Contactos desta conta.

#Guardar y volver

Dos Botones bajo el panel, con su evento onClick:

Guardar (icono save):

const ok = await keplin.data.store("conta").save();
if (ok) {
  keplin.ui.toast("Conta guardada");
  keplin.nav.go("/contas");
}

Volver (icono arrow-left):

keplin.nav.go("/contas");

save() valida primero — obligatorios y reglas — y solo guarda si todo pasa; devuelve true cuando guardó. Por eso el aviso y la navegación están dentro del if.

#La pantalla Oportunidades — el tablero kanban

Abre la pantalla Oportunidades.

1. Una Etiqueta arriba, con el texto Oportunidades.
2. Arrastra un Kanban debajo de ella, a todo el ancho.
3. En la categoría Datos, crea el datastore de lista sobre la API oportunidades (sin filtro — el tablero lo muestra todo), con Por página a 50.
4. En Campo de estado (columna), elige fase. Es este campo el que dice en qué columna vive cada tarjeta — y es el que se escribe cuando alguien arrastra una tarjeta.
5. En Fuente de las columnas, elige Estática y usa + añadir columna seis veces:

Valor	Etiqueta	Color
prospecao	Prospeção	gris
qualificacao	Qualificação	azul
proposta	Proposta	ámbar
negociacao	Negociação	morado
fechada_ganha	Ganha	verde
fechada_perdida	Perdida	rojo

6. Activa Permitir arrastrar tarjetas y Recuento de tarjetas; deja Columna para sin categoría desactivada.
7. En Template de la tarjeta, di qué muestra cada tarjeta:

Campo	Papel
titulo	Título
conta.nome	Leyenda
valor	Valor

8. Bajo el tablero, añade una Tabla con el título Todas as oportunidades, conectada a un datastore de lista sobre oportunidades, con las columnas titulo, conta.nome, valor, fase, data_fecho y responsavel.

#Ver el resultado

No hay botón de guardar en las pantallas: los cambios se guardan solos, y la esquina superior derecha dice en qué punto están (Guardando…, Guardado).

Para ver la pantalla de verdad, haz clic en Previsualizar: la plataforma guarda lo que esté pendiente y abre la pantalla en la app real, en una pestaña nueva del navegador. Pasas por el login como cualquier usuario — las cuentas que entran en la app se crean en la etapa Publicar y usar, y hasta entonces puedes usar la que ya exista.

#¿Por qué no…?

• ¿Por qué no aparece mi API en la lista de datastores? La API está en borrador. Ábrela y activa Publicada.
• ¿Por qué se abre siempre una ficha vacía? El datastore de registro no tiene condiciones en Qué registro cargar (clave), o el parámetro id no está llegando en la ruta. Confirma que la ruta es /ficha-de-conta/:id.
• ¿Por qué no veo la columna conta.nome? El navigator no está incluido en los Campos incluidos de la API de tabla — o el datastore se configuró antes de marcarlo. Reabre Configurar datastore y vuelve a elegir la API para refrescar el retrato de los campos.
• ¿Por qué el kanban no deja arrastrar? Falta la clave primaria en el datastore, o la acción Update en la API de tabla.
• ¿Por qué el gráfico está vacío? El Campo de categoría o los Campos de valor no están elegidos — o el filtro del datastore no deja pasar ninguna fila.

Las pantallas existen, pero aún no hay cómo saltar entre ellas. Próxima etapa: navegación y tema.