Datastores en gegevens

Een scherm praat niet rechtstreeks met de database: het praat met datastores — gegevenscontainers van het scherm die records laden via de tabel-API's van de app. De widgets koppelen aan de datastores: een Tabel toont de rijen van een lijst-datastore, de velden van een formulier lezen uit en schrijven naar een record-datastore.

Dit is de schakel tussen twee hoofdstukken: de tabel-API's maakt u op het gegevensmodel (hoofdstuk API's & GraphQL); hier koppelt u het scherm eraan.

#De twee soorten datastore

Soort	Wat die laadt	Waarvoor
Record	ÉÉN record (of een nieuw, leeg record)	Formulieren: de velden koppelen aan de velden van het record, en aan het eind slaat u op.
Lijst	Een verzameling records	Tabellen, lijsten, kaarten, grafieken, kanbans, kalenders.

Datastores kunnen op twee plekken leven:

• Op het scherm — aangemaakt in de inspector zonder selectie, in de categorie Gegevens. Zij worden gedeeld: meerdere widgets kunnen uit dezelfde lezen, en dat is wat u voor formulieren en voor master-detailrelaties gebruikt.
• Binnen een widget — de gegevenswidgets (Tabel, Grafiek, KPI…) hebben hun eigen datastore in hun categorie Gegevens. Dat is het meest voorkomende geval voor onafhankelijke grids en grafieken.

De motor is op beide plekken dezelfde; het enige verschil zit in de waardebronnen die in de filters beschikbaar zijn (zie de koppelingen).

#Een datastore op het scherm aanmaken

1. Klik op een lege zone van het canvas zodat de inspector het scherm toont.
2. Klik in de categorie Gegevens op + record of + lijst.
3. Klik op de aangemaakte datastore om het modale venster Datastore instellen te openen.
4. Geef hem een Naam van de datastore — met deze naam vinden de widgets en de code hem terug (bijv.: conta, contas).
5. Kies bij Tabel-API de API die de gegevens levert. De velden van de API komen beschikbaar voor kolommen, koppelingen en filters.

#Record-datastore — welk record te laden

Een record-datastore beantwoordt één vraag: welk record? Het antwoord geeft u bij Welk record te laden (sleutel):

1. Klik op + sleutelveld.
2. Kies het veld (standaard de primaire sleutel), de operator en de waarde — meestal een Param uit de route: het scherm Ficha de Conta ontvangt id in het adres en laadt de account met dat id.
3. Meerdere voorwaarden vormen een samengestelde sleutel — ze moeten allemaal kloppen.

Zonder voorwaarden laadt de datastore een nieuw (leeg) record — zo dient hetzelfde formulierscherm ook om aan te maken: zonder id geopend begint het blanco; opgeslagen doet het de invoeging.

#Lijst-datastore — filters en laden

#Filters (where)

De Filters (where) zijn voorwaarden die gelden telkens wanneer de gegevens gelezen worden — hier beperkt u wat er uit de database komt. Elke voorwaarde is veld / operator / waarde; + filter toevoegen voegt voorwaarden toe en + groep maakt geneste subgroepen, waarbij Alle (AND) of Elke (OR) bepaalt hoe ze gecombineerd worden.

Voorbeeld uit Klantenbeheer: het scherm Contas filtert estado eq "activa"; het paneel "mijn accounts" voegt gestor eq → Sessie ▸ username toe.

#Laden en pagina

Optie	Wat die doet
Alles laden	Haalt alle records van het filter in één keer op — van pagina wisselen, sorteren en filteren op het scherm gaat dan direct.
Eén pagina per keer	Gaat bij elke paginawissel naar de server — voor grote tabellen, waar alles ophalen geen zin heeft.
Per pagina	Hoeveel rijen er tegelijk op het scherm te zien zijn — niet te verwarren met hoeveel records er gelezen worden.
Automatisch laden	De gegevens lezen zodra het scherm opent. Schakel dit uit als u pas na een actie wilt laden (een knop "Zoeken", bijvoorbeeld).

#De koppelingen — waar een waarde vandaan komt

Telkens wanneer een filter, een sleutel of een eigenschap een waarde nodig heeft, gebruikt u hetzelfde stuk: de koppeling. De eerste keuzelijst noemt de bron; de rest verandert daarmee mee:

Bron	Wat het is
Vast	Een waarde die u daar ter plekke invult, gelijk voor iedereen.
Param	Een routeparameter van het scherm (sectie Routeparameters).
Sessie	Een veld van de aangemelde gebruiker (userId, username, name).
State	Een waarde die met keplin.state.set() in het geheugen van de app bewaard is — beschikbaar op elk scherm.
Datastore	Een veld uit een andere datastore van het scherm — de basis van master-detail.
Widget	De huidige waarde van een andere invoerwidget — de basis van de interactieve filters.

De bronnen Datastore en Widget bestaan alleen in de datastores binnen widgets — zij hangen af van de rest van het scherm. In de datastores van het scherm blijven de eerste vier over.

Met deze stukken bouwt u de dagelijkse patronen zonder code:

• Master-detail — de tabel met kansen van de account: in de datastore van de tabel het filter contaId eq → Datastore ▸ conta ▸ id. Een andere account selecteren laadt het detail opnieuw.
• Filter op tekst — een Tekstvak "zoeken" en, in de datastore van de tabel, nome contains → Widget ▸ het tekstvak. (Om pas te filteren bij een klik op een knop, doet u dat via een gebeurtenis — zie Gebeurtenissen en de SDK.)

#Formuliervelden aan een record koppelen

Elk formulierveld heeft, in de categorie Gegevens, de sectie Gegevenskoppeling: kies de record-datastore en het veld. Vanaf dat moment toont het invoerveld de geladen waarde en blijven de wijzigingen in de datastore staan — niet opgeslagen — tot iemand opslaat.

De laatste stap is een knop waarvan de gebeurtenis opslaat:

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

Deze code is precies wat de vooraf bepaalde actie Datastore opslaan van de gebeurtenis-editor voor u invoegt. save() valideert eerst (verplichte velden, regels, validatiescripts) en slaat alleen op als alles slaagt; het geeft true terug als er opgeslagen is.

#Het modale venster Datastore instellen, veld voor veld

Veld	Record	Lijst
Naam van de datastore	✓	✓
Tabel-API	✓	✓
Welk record te laden (sleutel)	✓	—
Filters (where)	—	✓
Laden / Per pagina	—	✓
Automatisch laden	✓	✓

#Datastores op openbare schermen

Op een scherm dat als Openbaar scherm (zonder sessie) gemarkeerd is, komen de gegevens alleen uit API's met openbare leestoegang: de keuzelijst toont alleen die, en een al gekozen API die niet openbaar is, wordt gemarkeerd — Deze API heeft geen openbare leestoegang — op een scherm zonder sessie laadt zij geen gegevens. Het lezen markeert u als openbaar in de editor van de API.

#De gegevens in de code

Alles wat de datastores doen zit ook in de SDK van de gebeurtenissen — keplin.data.store("naam") geeft de datastore op naam terug, met reload(), setWhere(), get()/set()/save() en aanverwanten. Het hoofdstuk Gebeurtenissen en de SDK loopt die langs.

#Waarom niet…?

• Waarom laadt hij geen gegevens? Kijk, op volgorde: staat Automatisch laden aan? Bestaat de gekozen API en is zij gepubliceerd? Is op een openbaar scherm het lezen van de API openbaar? Sluit het filter niet alles uit?
• Waarom opent er altijd een leeg record? De record-datastore heeft geen voorwaarden bij Welk record te laden (sleutel) — of de parameter die in de voorwaarde gebruikt wordt, komt niet in de route aan.
• Waarom verschijnt de nieuwe kolom niet nadat ik het model gewijzigd heb? De datastore bewaart een momentopname van de velden van de API van toen u haar koos. Open Datastore instellen opnieuw en kies de API nogmaals om de momentopname bij te werken.
• Waarom is de paginering traag? U staat op Eén pagina per keer met veel gangen naar de server — of op Alles laden zonder filters op een enorme tabel. Stem de modus af op de werkelijke omvang van de gegevens.