Datastore e dati

Una schermata non parla direttamente con il database: parla con i datastore — contenitori di dati della schermata che caricano i record attraverso le API di tabella dell'app. I widget si collegano ai datastore: una Tabella mostra le righe di un datastore di elenco, i campi di un modulo leggono e scrivono in un datastore di record.

Questo è l'anello fra due capitoli: le API di tabella si creano sul modello dati (capitolo API & GraphQL); qui si collega la schermata a esse.

#I due tipi di datastore

Tipo	Che cosa carica	Per che cosa
Record	UN record (o un record nuovo, vuoto)	Moduli: i campi si collegano ai campi del record, e alla fine si salva.
Elenco	Una collezione di record	Tabelle, elenchi, card, grafici, kanban, calendari.

I datastore possono vivere in due posti:

• Nella schermata — creati nell'inspector senza selezione, nella categoria Dati. Sono condivisi: più widget possono leggere dallo stesso, ed è ciò che si usa per i moduli e per le relazioni master-dettaglio.
• Dentro un widget — i widget di dati (Tabella, Grafico, KPI…) hanno il loro datastore nella loro categoria Dati. È il caso più comune per griglie e grafici indipendenti.

Il motore è lo stesso nei due posti; l'unica differenza sta nelle origini di valore disponibili nei filtri (vedi i collegamenti).

#Creare un datastore nella schermata

1. Clicca su una zona vuota del canvas perché l'inspector mostri la schermata.
2. Nella categoria Dati, clicca su + record o + elenco.
3. Clicca sul datastore creato per aprire il modale Configura datastore.
4. Dagli un Nome del datastore — è con questo nome che i widget e il codice lo trovano (es.: conta, contas).
5. In API di tabella, scegli l'API che serve i dati. I campi dell'API restano disponibili per colonne, collegamenti e filtri.

#Datastore di record — quale record caricare

Un datastore di record risponde a una domanda: quale record? La risposta si dà in Quale record caricare (chiave):

1. Clicca su + campo della chiave.
2. Scegli il campo (per impostazione predefinita, la chiave primaria), l'operatore e il valore — tipicamente un Param del percorso: la schermata Scheda Account riceve id nell' indirizzo e carica l'account con quell'id.
3. Più condizioni formano una chiave composta — devono corrispondere tutte.

Senza condizioni, il datastore carica un record nuovo (vuoto) — è così che la stessa schermata di modulo serve anche per creare: aperta senza id, comincia in bianco; salvata, fa l'inserimento.

#Datastore di elenco — filtri e caricamento

#Filtri (where)

I Filtri (where) sono condizioni applicate ogni volta che i dati vengono letti — è qui che si limita ciò che arriva dal database. Ogni condizione è campo / operatore / valore; + aggiungi filtro aggiunge condizioni e + gruppo crea sottogruppi annidati, con Tutte (AND) o Qualsiasi (OR) a decidere come si combinano.

Esempio da Gestione Clienti: la schermata Account filtra estado eq "activa"; il pannello "i miei account" aggiunge gestor eq → Sessione ▸ username.

#Caricamento e pagina

Opzione	Che cosa fa
Carica tutto	Porta tutti i record del filtro in una volta — cambiare pagina, ordinare e filtrare nella schermata diventa istantaneo.
Una pagina per volta	Va al server a ogni cambio di pagina — per tabelle grandi, dove portare tutto non ha senso.
Per pagina	Quante righe si vedono per volta nella schermata — da non confondere con quanti record vengono letti.
Carica automaticamente	Leggere i dati appena la schermata si apre. Disattivalo se preferisci caricare solo dopo un'azione (un pulsante "Cerca", per esempio).

#I collegamenti — da dove viene un valore

Ogni volta che un filtro, una chiave o una proprietà ha bisogno di un valore, usi lo stesso pezzo: il collegamento. Il primo selettore dice l'origine; il resto cambia a seconda di essa:

Origine	Che cos'è
Fisso	Un valore scritto lì stesso, uguale per tutti.
Param	Un parametro del percorso della schermata (sezione Parametri del percorso).
Sessione	Un campo dell'utente con sessione avviata (userId, username, name).
Stato	Un valore salvato nella memoria dell'app con keplin.state.set() — disponibile in tutte le schermate.
Datastore	Un campo di un altro datastore della schermata — la base del master-dettaglio.
Widget	Il valore attuale di un altro widget di input — la base dei filtri interattivi.

Le origini Datastore e Widget esistono solo nei datastore dentro i widget — dipendono dal resto della schermata. Nei datastore della schermata restano le quattro prime.

Con questi pezzi si montano gli schemi di tutti i giorni senza codice:

• Master-dettaglio — la tabella delle opportunità dell'account: nel datastore della tabella, filtro contaId eq → Datastore ▸ conta ▸ id. Selezionare un altro account ricarica il dettaglio.
• Filtro per testo — una Casella di testo "cerca" e, nel datastore della tabella, nome contains → Widget ▸ la casella. (Per filtrare solo cliccando su un pulsante, si fa per evento — vedi Eventi e SDK.)

#Collegare i campi di modulo a un record

Ogni campo di modulo ha, nella categoria Dati, la sezione Collegamento ai dati: scegli il datastore di record e il campo. Da lì in poi l'input mostra il valore caricato e le modifiche restano nel datastore — da salvare — finché qualcuno non salva.

Il passo finale è un pulsante il cui evento salva:

const ok = await keplin.data.store("conta").save();
if (ok) {
  keplin.ui.toast("Salvato.", "success");
}

Questo codice è esattamente ciò che l'azione predefinita Salva datastore dell' editor di eventi inserisce per te. save() valida prima (obbligatori, regole, script di validazione) e salva solo se passa tutto; restituisce true se ha salvato.

#Il modale Configura datastore, campo per campo

Campo	Record	Elenco
Nome del datastore	✓	✓
API di tabella	✓	✓
Quale record caricare (chiave)	✓	—
Filtri (where)	—	✓
Caricamento / Per pagina	—	✓
Carica automaticamente	✓	✓

#Datastore in schermate pubbliche

In una schermata marcata Schermata pubblica (senza sessione), i dati arrivano solo da API con lettura pubblica: il selettore mostra solo quelle, e un'API già scelta che non sia pubblica viene segnalata — Questa API non ha lettura pubblica — in una schermata senza sessione non carica dati. La lettura si marca come pubblica nell' editor dell'API.

#I dati nel codice

Tutto ciò che i datastore fanno è anche nell'SDK degli eventi — keplin.data.store("nome") restituisce il datastore per nome, con reload(), setWhere(), get()/set()/save() e compagnia. Il capitolo Eventi e SDK lo percorre.

#Perché no…?

• Perché non carica i dati? Guarda, in ordine: Carica automaticamente è attivo? L'API scelta esiste ed è pubblicata? In una schermata pubblica, la lettura dell'API è pubblica? Il filtro non sta escludendo tutto?
• Perché apre sempre un record vuoto? Il datastore di record non ha condizioni in Quale record caricare (chiave) — oppure il parametro usato nella condizione non sta arrivando nel percorso.
• Perché ho cambiato il modello e la colonna nuova non appare? Il datastore conserva una fotografia dei campi dell'API di quando l'hai scelta. Riapri Configura datastore e riscegli l'API per aggiornare la fotografia.
• Perché la paginazione è lenta? Sei in Una pagina per volta con molti viaggi al server — oppure in Carica tutto senza filtri su una tabella enorme. Adatta la modalità alla dimensione reale dei dati.