Datastorer och data

En skärm talar inte direkt med databasen: den talar med datastorer — databehållare på skärmen som laddar poster via appens tabell-API:er. Widgetarna binds till datastorerna: en Tabell visar raderna från en listdatastore, och ett formulärs fält läser och skriver i en postdatastore.

Det här är länken mellan två kapitel: tabell-API:erna skapas ovanpå datamodellen (kapitlet API:er & GraphQL); här binds skärmen till dem.

#De två typerna av datastore

Typ	Vad den laddar	Till vad
Post	EN post (eller en ny, tom post)	Formulär: fälten binds till postens fält, och i slutet sparar man.
Lista	En samling poster	Tabeller, listor, kort, diagram, kanban-tavlor, kalendrar.

Datastorer kan leva på två ställen:

• På skärmen — skapade i inspektorn utan markering, i kategorin Data. De är delade: flera widgetar kan läsa från samma, och det är det man använder för formulär och för master–detalj-relationer.
• Inuti en widget — datawidgetarna (Tabell, Diagram, KPI…) har sin egen datastore i sin kategori Data. Det är det vanligaste fallet för fristående rutnät och diagram.

Motorn är densamma på båda ställena; den enda skillnaden ligger i vilka värdekällor som är tillgängliga i filtren (se bindningarna).

#Skapa en datastore på skärmen

1. Klicka på en tom yta på canvasen så att inspektorn visar skärmen.
2. Klicka på + post eller + lista i kategorin Data.
3. Klicka på den skapade datastoren för att öppna modalen Konfigurera datastore.
4. Ge den ett Datastorens namn — det är med det namnet widgetarna och koden hittar den (t.ex. conta, contas).
5. Välj under API det API som levererar data. API:ets fält blir tillgängliga för kolumner, bindningar och filter. I ett list-datastore visas även pipeline-API:erna, med märket pipeline: de returnerar hela listan, utan filter eller sidor.

#Postdatastore — vilken post som ska laddas

En postdatastore svarar på en fråga: vilken post? Svaret ger du i Vilken post som ska laddas (nyckel):

1. Klicka på + nyckelfält.
2. Välj fältet (som standard primärnyckeln), operatorn och värdet — vanligtvis en Param från rutten: skärmen Kontouppgifter tar emot id i adressen och laddar kontot med det id:t.
3. Flera villkor bildar en sammansatt nyckel — alla måste matcha.

Utan villkor laddar datastoren en ny (tom) post — det är så samma formulärskärm också duger till att skapa: öppnad utan id börjar den blank; sparad gör den en infogning.

Om villkoren inte hittar någon post (ett id som inte längre finns, eller som ligger utanför räckvidden för rollen hos den som öppnar skärmen) meddelar appen att den begärda posten inte finns, och formuläret sparar inte. Bara en nyckel som skrivs i ett fält på skärmen (en naturlig nyckel, som en artikelkod) är fortfarande nyckeln till en ny post.

#Listdatastore — filter och laddning

#Filter (where)

Filter (where) är villkor som tillämpas varje gång data läses — det är här man begränsar vad som kommer från databasen. Varje villkor är fält / operator / värde; + lägg till filter lägger till villkor och + grupp skapar nästlade undergrupper, där Alla (AND) eller Någon (OR) avgör hur de kombineras.

Exempel från Kundhantering: skärmen Konton filtrerar estado eq "activa"; panelen ”mina konton” lägger till gestor eq → Session ▸ username.

Operatorerna:

Operator	Vad den jämför
eq / neq	Lika med / inte lika med värdet. neq tar med poster där fältet är tomt.
contains, startsWith, endsWith	Text som innehåller, börjar eller slutar med värdet.
gt, gte, lt, lte	Större, större eller lika, mindre, mindre eller lika — tal och datum.
in / nin	Någon av / ingen av en lista värden. Värdet är en lista: flera värden åtskilda med kommatecken, eller värdet från en Lista med Flerval kopplad via Widget — så filtreras en tabell på flera center eller flera statusar samtidigt. nin tar med poster där fältet är tomt.

Ett villkor med tomt värde (tom sökruta, lista utan val) filtrerar inget — skärmen visar allt tills personen väljer.

Varje filtervärde omvandlas efter kolumnens typ: i en textkolumn förblir ett personnummer eller ett postnummer (”0012”) text, och i en decimalkolumn är ”12,5” ett tal.

#Laddning och sida

Alternativ	Vad det gör
Ladda allt	Hämtar alla poster i filtret på en gång — att byta sida, sortera och filtrera på skärmen blir omedelbart.
En sida i taget	Går till servern vid varje sidbyte — för stora tabeller, där det inte är rimligt att hämta allt.
Per sida	Hur många rader som visas åt gången på skärmen — inte att förväxla med hur många poster som läses.
Ladda automatiskt	Läser data så snart skärmen öppnas. Stäng av om du hellre laddar först efter en åtgärd (en ”Sök”-knapp, till exempel).

Utan Ladda automatiskt läser listan när någon ber om det: en reload() (på en knapp ”Sök”, till exempel), ett byte av sida eller sortering, eller ett tillämpat filter. Att ändra ett fält på skärmen får den inte att läsa av sig själv.

När det gällande filtret ändras (ett fält på skärmen, en parameter, appens tillstånd) går listan tillbaka till första sidan. Om sidan du var på inte längre finns (du tog till exempel bort sista posten på sista sidan) går listan till den sista sida som finns.

#Bindningarna — varifrån ett värde kommer

Varje gång ett filter, en nyckel eller en egenskap behöver ett värde använder du samma del: bindningen. Den första väljaren anger källan; resten ändras efter den:

Källa	Vad det är
Fast	Ett värde som skrivs på plats, lika för alla.
Param	En parameter från skärmens rutt (avsnittet Ruttparametrar).
Session	Ett fält från den inloggade användaren (userId, username, name).
Tillstånd	Ett värde som sparats i appens minne med keplin.state.set() — tillgängligt på alla skärmar.
Datastore	Ett fält från en annan datastore på skärmen — grunden för master–detalj.
Widget	Det aktuella värdet i en annan inmatningswidget — grunden för interaktiva filter.

Även ett fält skriver till tillståndet: i fältets Databindning, välj Tillstånd och skriv Nyckel. Ett filter med källan Tillstånd och samma nyckel läser data igen när värdet ändras. Så filtrerar ett widgetområde i listen sidorna; se Appens navigering.

Källorna Datastore och Widget finns bara i datastorer inuti widgetar — de beror på resten av skärmen. I skärmens egna datastorer finns de fyra första.

Med de här delarna bygger man vardagens mönster utan kod:

• Master–detalj — kontots tabell med affärsmöjligheter: i tabellens datastore, filtret contaId eq → Datastore ▸ conta ▸ id. Att välja ett annat konto laddar om detaljen.
• Textfilter — en Textruta ”sök” och, i tabellens datastore, nome contains → Widget ▸ rutan. (För att filtrera först vid ett knapptryck gör man det via en händelse — se Händelser och SDK:t.)

#Binda formulärfält till en post

Varje formulärfält har, i kategorin Data, avsnittet Databindning: välj postdatastoren och fältet. Därefter visar inmatningsfältet det laddade värdet och ändringarna stannar i datastoren — osparade — tills någon sparar.

Sista steget är en knapp vars händelse sparar:

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

Den här koden är exakt vad den fördefinierade åtgärden Spara datastore i händelseredigeraren infogar åt dig. save() validerar först (obligatoriska fält, regler, valideringsskript) och sparar bara om allt passerar; den returnerar true om det sparades.

När du sparar en post som redan fanns skickas bara de fält som ändrats sedan den lästes. Ett tömt fält sparas tomt (null i databasen), och i ett decimalfält läses ”12,5” som ett tal.

Med osparade ändringar ber sidan om bekräftelse när du lämnar den: via menyerna, webbläsarens Bakåt-knapp eller när fliken stängs. En modal frågade redan när den stängdes. Navigering i kod (keplin.nav.go) frågar inte: den som anropar den har redan bestämt sig, och har ofta just sparat.

När en ny post sparas skickas inte ett fält som skärmen inte visar: i en kolumn med ett standardvärde i databasen, eller som databasen genererar, gäller det värdet; en obligatorisk kolumn utan standardvärde måste finnas på skärmen, och formuläret säger vilken som saknas. En nyckel som skrivs i ett fält på skärmen (en naturlig nyckel, som en artikelkod) tillhör en ny post; satt i kod med set() är den fortfarande nyckeln till en post som ska ändras. Att spara en post som under tiden har slutat finnas ger ett fel, inte ”Sparad”.

#Modalen Konfigurera datastore, fält för fält

Fält	Post	Lista
Datastorens namn	✓	✓
API	✓	✓
Vilken post som ska laddas (nyckel)	✓	—
Filter (where)	—	✓
Laddning / Per sida	—	✓
Ladda automatiskt	✓	✓

#Datastorer på publika skärmar

På en skärm som är markerad Publik skärm (utan session) kommer data bara från API:er med publik läsning: väljaren visar bara dessa, och ett redan valt API som inte är publikt markeras — Det här API:et har ingen publik läsning — på en skärm utan session laddas inga data. Läsningen markeras som publik i API-editorn.

#Data i koden

Allt som datastorerna gör finns också i händelsernas SDK — keplin.data.store("namn") returnerar datastoren via dess namn, med reload(), setWhere(), get()/set()/save() och sällskap. Kapitlet Händelser och SDK:t går igenom det.

#Varför inte…?

• Varför laddas inga data? Kontrollera, i tur och ordning: är Ladda automatiskt påslaget? Finns det valda API:et, och är det publicerat? Är API:ets läsning publik, om skärmen är publik? Utesluter filtret allt?
• Varför öppnas alltid en tom post? Postdatastoren har inga villkor under Vilken post som ska laddas (nyckel) — eller så kommer inte parametern som villkoret använder fram i rutten.
• Varför dyker den nya kolumnen inte upp när jag ändrat modellen? Datastoren sparar en ögonblicksbild av API:ets fält från när du valde det. Öppna Konfigurera datastore igen och välj API:et på nytt för att uppdatera bilden. Vad varje redan vald kolumn är (typ, obligatorisk eller inte, standardvärde, datum) uppdateras av sig självt när skärmen öppnas; bara nya kolumner behöver väljas.
• Varför är sidindelningen långsam? Du kör En sida i taget med många vändor till servern — eller Ladda allt utan filter i en enorm tabell. Anpassa läget till datamängdens verkliga storlek.