Le schermate

Questa è la tappa più lunga della guida, e quella che dà un volto all'app. Alla fine hai quattro schermate disegnate e funzionanti sui dati veri del modello: un Início con indicatori e un grafico, un elenco di Contas, una Ficha de Conta che salva, e una bacheca di Oportunidades con cartoncini trascinabili.

Prima delle schermate, però, c'è un passo breve che le rende possibili.

#Prima le API di tabella

Una schermata non parla con il database. Parla con i datastore — i contenitori di dati di ogni schermata — e i datastore leggono e scrivono attraverso le API di tabella dell'app. Un'API di tabella punta a un'entità del modello e genera, da sola, le operazioni di lettura e scrittura.

Ne creiamo tre, una per entità:

1. Scegli il pannello Codice nella barra laterale.
2. Sulla riga API, clicca sul + (Nuova API).
3. In Nome, scrivi contas. Il nome è la base delle operazioni (getContas, addContas, updateContas, deleteContas) — quindi non mettergli prefissi come get o listar.
4. Clicca su Crea API. Il costruttore si apre sulla scheda Costruisci.
5. Nella sezione Pipeline, scegli il blocco Tabella.
6. Nel campo Tabella, scegli Dados CRM ▸ Contas.
7. In Azioni esposte, lascia Select, Insert, Update e Delete spuntati — il CRM ha bisogno di tutti e quattro.
8. Lascia Accesso pubblico (senza sessione) tutto disattivato: questa app è per chi ha una sessione avviata.
9. In Campi inclusi, verifica che siano spuntati i campi che le schermate useranno. Per gli account, sono tutti.
10. Attiva l'interruttore Pubblicata e clicca su Salva.

Ripeti per le altre due:

API	Entità	Azioni	Note
contas	Contas	Select, Insert, Update, Delete	Tutti i campi.
contactos	Contactos	Select, Insert, Update, Delete	Include il navigator conta (solo il campo nome).
oportunidades	Oportunidades	Select, Insert, Update, Delete	Include il navigator conta (solo il campo nome).

I navigator sono ciò che permette di mostrare il nome dell'account accanto a un'opportunità senza scrivere una riga di SQL: spuntali nell'elenco dei campi inclusi, e il campo conta.nome diventa disponibile nelle schermate.

#Creare le quattro schermate

Le schermate vivono nel pannello UI, nella sezione Schermate.

1. Scegli il pannello UI nella barra laterale.
2. Sulla riga Schermate, clicca sul pulsante Nuova schermata.
3. Scrivi il nome e conferma con Crea. La schermata si apre subito nello spazio di lavoro.

Creale tutte e quattro in una volta, in quest'ordine:

Nome della schermata	Percorso	Che cosa diventerà
Início	/inicio	Il cruscotto commerciale, con indicatori e grafico.
Contas	/contas	L'elenco degli account.
Ficha de Conta	/ficha-de-conta	Il modulo di un account.
Oportunidades	/oportunidades	La bacheca kanban.

Il Percorso è derivato dal nome e si vede (e si modifica) nell'ispettore, quando nessun widget è selezionato. Lasciali come stanno — la guida vi si riferisce più avanti.

#La schermata Início — il cruscotto commerciale

Apri la schermata Início. Il progetto ha quattro pezzi: un titolo, una fascia di indicatori, un grafico e una tabella.

#Il titolo

1. Trascina un'Etichetta dalla palette in cima al canvas.
2. Nella categoria Contenuto dell'ispettore, scrivi il testo Cruscotto commerciale.
3. Nella categoria Aspetto, alza la Dimensione del testo — è il titolo della pagina.

#La fascia di indicatori

Quattro numeri affiancati si fanno con un widget KPI di quattro indicatori, non con quattro widget: l'allineamento e la spaziatura restano garantiti.

1. Trascina un KPI sotto il titolo e allargalo a tutta la larghezza.
2. Nella categoria Dati, la sezione Indicatori comincia con uno. Usa Aggiungi indicatore finché non ne hai quattro.
3. Ogni indicatore ha un'Etichetta, un'icona, un Set di dati proprio (il suo datastore) e un valore con Aggregazione.

Configurali così:

Etichetta	Datastore (API di tabella)	Filtro	Valore
Account attivi	contas	—	Conteggio di id
Opportunità aperte	oportunidades	fase ≠ fechada_ganha e fase ≠ fechada_perdida	Conteggio di id
Valore in pipeline	oportunidades	lo stesso filtro	Somma di valor
Chiuso questo trimestre	oportunidades	fase = fechada_ganha	Somma di valor

Nei due indicatori di denaro, apri il Formato e scegli la valuta EUR con zero decimali — 475.850 si legge meglio di 475850.

#Il grafico

1. Trascina un Grafico sulla metà sinistra, sotto il KPI.
2. Nella categoria Dati, crea il datastore di elenco sull'API oportunidades.
3. In Tipo di grafico, scegli Barre.
4. In Campo di categoria (asse X / fette), scegli fase.
5. In Campi di valore, aggiungi valor.
6. Nella categoria Aspetto, attiva Mostra titolo e scrivi Pipeline per fase.

#La tabella delle prossime chiusure

1. Trascina una Tabella sulla metà destra, accanto al grafico.
2. Nella categoria Dati, crea il datastore di elenco su oportunidades, con il filtro delle fasi aperte (lo stesso degli indicatori), ordinato per data_fecho crescente e Per pagina a 8.
3. Nella categoria Dati, sezione Colonne, definisci quattro colonne:

Campo	Intestazione
titulo	Opportunità
conta.nome	Account
valor	Valore (€)
data_fecho	Chiusura

4. Attiva Mostra titolo e scrivi Prossime chiusure.

#La schermata Contas — l'elenco

Apri la schermata Contas. Sono tre widget.

1. Un'Etichetta in cima, con il testo Account.
2. Un Pulsante nell'angolo in alto a destra: nella categoria Contenuto, testo Nuovo account e icona plus.
3. Una Tabella che occupa il resto della schermata. Nella categoria Dati, crea il datastore di elenco sull'API contas, ordinato per nome crescente, e definisci le colonne:

Campo	Intestazione
nome	Nome
sector	Settore
cidade	Città
telefone	Telefono
email	Email
estado	Stato

Manca collegare i due gesti che rendono questo elenco utile a qualcosa. Entrambi si scrivono nella categoria Eventi, in TypeScript:

Sul Pulsante, nell'evento onClick — aprire la scheda in bianco, per creare:

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

Sulla Tabella, nell'evento onRowClick — aprire la scheda della riga cliccata:

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

#La schermata Ficha de Conta — il modulo

Questa è la schermata con più pezzi, e quella che mostra meglio come funzionano i dati. Apri la schermata Ficha de Conta.

#Il parametro del percorso

1. Clicca su una zona vuota del canvas — l'ispettore passa a mostrare la schermata.
2. Nella sezione Parametri del percorso, clicca su + aggiungi parametro e scrivi id.
3. Lascia Obbligatorio disattivato. È deliberato: senza id la schermata si apre in bianco, ed è così che lo stesso modulo serve a creare un account nuovo.

Il Percorso diventa /ficha-de-conta/:id.

#I due datastore della schermata

Sempre con la schermata selezionata, nella categoria Dati:

1. Clicca su + record. Clicca sul datastore creato per aprire la finestra Configura datastore.
2. In Nome del datastore, scrivi conta.
3. In API di tabella, scegli contas.
4. In Quale record caricare (chiave), clicca su + campo della chiave e monta la condizione: campo id, operatore eq, valore Param ▸ id.
5. Lascia Carica automaticamente attivo e chiudi con Fatto.

Ora il secondo, per i contatti dell'account:

1. Clicca su + elenco e aprilo.
2. Nome contactosConta, API di tabella contactos.
3. In Filtri (where), aggiungi: campo conta_id, operatore eq, valore Param ▸ id.
4. Ordina per nome crescente.

#Il modulo

1. Trascina un Pannello sulla sinistra del canvas. Nella categoria Aspetto, attiva Mostra titolo e scrivi Dati dell'azienda.
2. Trascina le Caselle di testo dentro il pannello — lasciare un widget dentro un pannello lo rende suo figlio. Per ognuna, nella categoria Contenuto scrivi l'etichetta e, nella categoria Dati, sezione Collegamento ai dati, scegli il datastore conta e il campo:

Etichetta	Campo	Obbligatorio
Nome	nome	sì
P. IVA	nif	no
Settore	sector	no
Città	cidade	no
Telefono	telefone	no
Email	email	no

3. Per lo stato, usa un Dropdown invece di una casella di testo: etichetta Stato, collegata a conta ▸ estado, Obbligatorio attivo, e opzioni statiche:

Valore	Etichetta
ativo	Attivo
prospeto	Potenziale
inativo	Inattivo

4. Trascina una Tabella sulla destra del pannello, collegata al datastore contactosConta, con le colonne nome (Nome), cargo (Ruolo) e telefone (Telefono), e il titolo Contatti di questo account.

#Salvare e tornare indietro

Due Pulsanti sotto il pannello, con il rispettivo evento onClick:

Salva (icona save):

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

Indietro (icona arrow-left):

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

save() valida prima — obbligatori e regole — e salva solo se tutto passa; restituisce true quando ha salvato. È per questo che l'avviso e la navigazione stanno dentro l'if.

#La schermata Oportunidades — la bacheca kanban

Apri la schermata Oportunidades.

1. Un'Etichetta in cima, con il testo Opportunità.
2. Trascina un Kanban sotto di essa, a tutta larghezza.
3. Nella categoria Dati, crea il datastore di elenco sull'API oportunidades (senza filtro — la bacheca mostra tutto), con Per pagina a 50.
4. In Campo di stato (colonna), scegli fase. È questo campo a dire in quale colonna vive ogni cartoncino — ed è quello che viene scritto quando qualcuno trascina un cartoncino.
5. In Origine delle colonne, scegli Statica e usa + aggiungi colonna sei volte:

Valore	Etichetta	Colore
prospecao	Prospezione	grigio
qualificacao	Qualificazione	blu
proposta	Proposta	ambra
negociacao	Negoziazione	viola
fechada_ganha	Vinta	verde
fechada_perdida	Persa	rosso

6. Attiva Consenti di trascinare le card e Conteggio delle card; lascia Colonna senza categoria disattivata.
7. In Template della card, di' che cosa mostra ogni cartoncino:

Campo	Ruolo
titulo	Titolo
conta.nome	Didascalia
valor	Valore

8. Sotto la bacheca, aggiungi una Tabella con il titolo Tutte le opportunità, collegata a un datastore di elenco su oportunidades, con le colonne titulo, conta.nome, valor, fase, data_fecho e responsavel.

#Vedere il risultato

Non c'è un pulsante di salvataggio nelle schermate: le modifiche si salvano da sole, e l'angolo in alto a destra dice a che punto sono (Salvataggio…, Salvato).

Per vedere la schermata sul serio, clicca su Anteprima: la piattaforma salva quello che è in sospeso e apre la schermata nell'app reale, in una nuova scheda del browser. Passi dal login come qualsiasi utente — gli account che entrano nell'app si creano nella tappa Pubblicare e usare, e fino ad allora puoi usare quello che già esiste.

#Perché non…?

• Perché non appare la mia API nell'elenco dei datastore? L'API è in bozza. Aprila e attiva Pubblicata.
• Perché apre sempre una scheda vuota? Il datastore di record non ha condizioni in Quale record caricare (chiave), oppure il parametro id non arriva nel percorso. Verifica che il percorso sia /ficha-de-conta/:id.
• Perché non vedo la colonna conta.nome? Il navigator non è incluso nei Campi inclusi dell'API di tabella — oppure il datastore è stato configurato prima che tu lo spuntassi. Riapri Configura datastore e riscegli l'API per rinfrescare il ritratto dei campi.
• Perché il kanban non lascia trascinare? Manca la chiave primaria nel datastore, o l'azione Update nell'API di tabella.
• Perché il grafico è vuoto? Il Campo di categoria o i Campi di valore non sono stati scelti — oppure il filtro del datastore non lascia passare nessuna riga.

Le schermate esistono, ma non c'è ancora modo di saltare fra loro. Prossima tappa: navigazione e tema.