Datastorer og data

En skjerm snakker ikke direkte med databasen: den snakker med datastorer — skjermens databeholdere, som laster poster gjennom tabell-API-ene i appen. Widgetene bindes til datastorene: en Tabell viser radene fra en liste-datastore, feltene i et skjema leser og skriver i en post-datastore.

Dette er leddet mellom to kapitler: tabell-API-ene lages oppå datamodellen (kapitlet API-er & GraphQL); her bindes skjermen til dem.

#De to typene datastore

Type	Hva den laster	Til hva
Post	ÉN post (eller en ny, tom post)	Skjemaer: feltene bindes til feltene i posten, og til slutt lagres det.
Liste	En samling poster	Tabeller, lister, kort, diagrammer, kanbaner, kalendere.

Datastorene kan bo på to steder:

• På skjermen — opprettet i inspektøren uten noe valgt, i kategorien Data. De er delte: flere widgets kan lese fra den samme, og det er det som brukes til skjemaer og til master–detalj-forhold.
• Inne i en widget — datawidgetene (Tabell, Diagram, KPI…) har sin egen datastore i kategorien Data hos seg. Det er det vanligste tilfellet for uavhengige rutenett og diagrammer.

Motoren er den samme begge steder; den eneste forskjellen ligger i verdikildene som er tilgjengelige i filtrene (se bindingene).

#Opprette en datastore på skjermen

1. Klikk på et tomt område på canvaset så inspektøren viser skjermen.
2. I kategorien Data, klikk på + post eller + liste.
3. Klikk på den opprettede datastoren for å åpne vinduet Konfigurer datastore.
4. Gi den et Navn på datastoren — det er med dette navnet widgetene og koden finner den (f.eks. conta, contas).
5. Under API, velg API-en som leverer dataene. Feltene i API-en blir tilgjengelige for kolonner, bindinger og filtre. I et liste-datastore vises også pipeline-API-ene, med merket pipeline: de returnerer hele listen, uten filtre eller sider.

#Post-datastore — hvilken post som skal lastes

En post-datastore svarer på ett spørsmål: hvilken post? Svaret gis under Hvilken post som skal lastes (nøkkel):

1. Klikk på + nøkkelfelt.
2. Velg feltet (som standard primærnøkkelen), operatoren og verdien — typisk en Param fra ruten: skjermen Ficha de Conta mottar id i adressen og laster kontoen med den id-en.
3. Flere betingelser danner en sammensatt nøkkel — alle må stemme.

Uten betingelser laster datastoren en ny (tom) post — det er slik den samme skjemaskjermen også tjener til å opprette: åpnet uten id, starter den blank; lagret, gjør den innsettingen.

Hvis betingelsene ikke finner noen post (en id som ikke finnes lenger, eller som ligger utenfor rekkevidden til rollen som åpner skjermen), melder appen at den forespurte posten ikke finnes, og skjemaet lagrer ikke. Bare en nøkkel som skrives i et felt på skjermen (en naturlig nøkkel, som en varekode) er fortsatt nøkkelen til en ny post.

#Liste-datastore — filtre og innlasting

#Filtre (where)

Filtre (where) er betingelser som brukes hver gang dataene leses — det er her du begrenser hva som kommer fra databasen. Hver betingelse er felt / operator / verdi; + legg til filter legger til betingelser og + gruppe lager nestede undergrupper, med Alle (AND) eller Minst én (OR) som avgjør hvordan de kombineres.

Eksempel fra Gestão de Clientes: skjermen Contas filtrerer estado eq "activa"; panelet «mine kontoer» legger til gestor eq → Økt ▸ username.

Operatorene:

Operator	Hva den sammenligner
eq / neq	Lik / ikke lik verdien. neq tar med poster der feltet er tomt.
contains, startsWith, endsWith	Tekst som inneholder, begynner eller slutter med verdien.
gt, gte, lt, lte	Større, større eller lik, mindre, mindre eller lik — tall og datoer.
in / nin	En av / ingen av en liste verdier. Verdien er en liste: flere verdier atskilt med komma, eller verdien fra en Liste med Flervalg knyttet via Widget — slik filtreres en tabell på flere sentre eller flere statuser samtidig. nin tar med poster der feltet er tomt.

En betingelse med tom verdi (tomt søkefelt, liste uten valg) filtrerer ingenting — skjermen viser alt til personen velger.

Hver filterverdi gjøres om etter kolonnens type: i en tekstkolonne forblir et organisasjonsnummer eller et postnummer («0012») tekst, og i en desimalkolonne er «12,5» et tall.

#Innlasting og side

Alternativ	Hva det gjør
Last inn alt	Henter alle postene i filteret på én gang — sidebytte, sortering og filtrering på skjermen blir umiddelbart.
Én side om gangen	Går til serveren ved hvert sidebytte — for store tabeller, der det ikke gir mening å hente alt.
Per side	Hvor mange rader som vises av gangen på skjermen — ikke å forveksle med hvor mange poster som leses.
Last inn automatisk	Lese dataene så snart skjermen åpnes. Slå av hvis du heller vil laste først etter en handling (en «Søk»-knapp, for eksempel).

Uten Last inn automatisk leser listen når noen ber om det: en reload() (på en knapp «Søk», for eksempel), et bytte av side eller sortering, eller et filter som brukes. Å endre et felt på skjermen får den ikke til å lese av seg selv.

Når det gjeldende filteret endres (et felt på skjermen, en parameter, appens tilstand), går listen tilbake til første side. Hvis siden du var på ikke finnes lenger (du slettet for eksempel den siste posten på siste side), går listen til den siste siden som finnes.

#Bindingene — hvor en verdi kommer fra

Hver gang et filter, en nøkkel eller en egenskap trenger en verdi, bruker du den samme brikken: bindingen. Den første velgeren sier kilden; resten endrer seg etter den:

Kilde	Hva det er
Fast	En verdi skrevet der og da, lik for alle.
Param	En ruteparameter for skjermen (seksjonen Ruteparametere).
Økt	Et felt fra den påloggede brukeren (userId, username, name).
Tilstand	En verdi lagret i appens minne med keplin.state.set() — tilgjengelig på alle skjermer.
Datastore	Et felt fra en annen datastore på skjermen — grunnlaget for master–detalj.
Widget	Den nåværende verdien til en annen input-widget — grunnlaget for interaktive filtre.

Også et felt skriver til tilstanden: i feltets Databinding, velg Tilstand og skriv Nøkkel. Et filter med kilden Tilstand og den samme nøkkelen leser dataene på nytt når verdien endres. Slik filtrerer et widgetområde i linjen sidene; se Appens navigasjon.

Kildene Datastore og Widget finnes bare i datastorene inne i widgets — de avhenger av resten av skjermen. I skjermens datastorer er det de fire første som gjelder.

Med disse brikkene bygges hverdagsmønstrene uten kode:

• Master–detalj — tabellen over salgsmuligheter for kontoen: i datastoren til tabellen, filteret contaId eq → Datastore ▸ conta ▸ id. Å velge en annen konto laster detaljen på nytt.
• Tekstfilter — et Tekstfelt «søk» og, i datastoren til tabellen, nome contains → Widget ▸ feltet. (For å filtrere først ved klikk på en knapp gjøres det via hendelse — se Hendelser og SDK-et.)

#Binde skjemafelt til en post

Hvert skjemafelt har, i kategorien Data, seksjonen Databinding: velg post-datastoren og feltet. Fra da av viser inputen den lastede verdien, og endringene blir liggende i datastoren — ulagret — til noen lagrer.

Det siste steget er en knapp hvis hendelse lagrer:

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

Denne koden er nøyaktig det den forhåndsdefinerte handlingen Lagre datastore i hendelseseditoren setter inn for deg. save() validerer først (påkrevde felt, regler, valideringsskript) og lagrer bare hvis alt passerer; den gir tilbake true hvis den lagret.

Når du lagrer en post som fantes fra før, sendes bare feltene som er endret siden den ble lest. Et tømt felt lagres tomt (null i databasen), og i et desimalfelt leses «12,5» som et tall.

Med endringer som ikke er lagret, ber siden om bekreftelse når du forlater den: via menyene, nettleserens Tilbake-knapp eller når fanen lukkes. En modal spurte allerede ved lukking. Navigering i kode (keplin.nav.go) spør ikke: den som kaller den, har allerede bestemt seg, og har ofte nettopp lagret.

Når en ny post lagres, sendes ikke et felt som skjermen ikke viser: i en kolonne med standardverdi i databasen, eller som databasen genererer, gjelder den verdien; en påkrevd kolonne uten standardverdi må være på skjermen, og skjemaet sier hvilken som mangler. En nøkkel som skrives inn i et felt på skjermen (en naturlig nøkkel, som en varekode) tilhører en ny post; satt i kode med set() er den fortsatt nøkkelen til en post som skal endres. Å lagre en post som i mellomtiden har sluttet å finnes, gir en feil, ikke «Lagret».

#Vinduet Konfigurer datastore, felt for felt

Felt	Post	Liste
Navn på datastoren	✓	✓
API	✓	✓
Hvilken post som skal lastes (nøkkel)	✓	—
Filtre (where)	—	✓
Innlasting / Per side	—	✓
Last inn automatisk	✓	✓

#Datastorer på offentlige skjermer

På en skjerm merket Offentlig skjerm (uten økt) kommer dataene kun fra API-er med offentlig lesing: velgeren viser bare dem, og en allerede valgt API som ikke er offentlig blir markert — Denne API-en har ikke offentlig lesing — på en skjerm uten økt laster den ikke data. Lesingen merkes som offentlig i API-editoren.

#Dataene i koden

Alt datastorene gjør finnes også i SDK-et for hendelsene — keplin.data.store("navn") gir tilbake datastoren etter navnet, med reload(), setWhere(), get()/set()/save() og resten. Kapitlet Hendelser og SDK-et går gjennom det.

#Hvorfor ikke…?

• Hvorfor lastes det ikke data? Sjekk, i rekkefølge: er Last inn automatisk på? Finnes API-en du valgte, og er den publisert? På en offentlig skjerm, er lesingen i API-en offentlig? Ekskluderer filteret alt?
• Hvorfor åpnes alltid en tom post? Post-datastoren har ingen betingelser under Hvilken post som skal lastes (nøkkel) — eller parameteren som brukes i betingelsen kommer ikke fram i ruten.
• Hvorfor endret jeg modellen uten at den nye kolonnen vises? Datastoren tar vare på et bilde av feltene i API-en fra da du valgte den. Åpne Konfigurer datastore på nytt og velg API-en igjen for å oppdatere bildet. Hva hver allerede valgte kolonne er (type, påkrevd eller ikke, standardverdi, dato) oppdateres av seg selv når skjermen åpnes; bare nye kolonner må velges.
• Hvorfor er pagineringen treg? Du står i Én side om gangen med mange turer til serveren — eller i Last inn alt uten filtre på en enorm tabell. Tilpass moduset til den virkelige størrelsen på dataene.