Datastores und Daten

Ein Bildschirm spricht nicht direkt mit der Datenbank: Er spricht mit Datastores — Datencontainern des Bildschirms, die Datensätze über die Tabellen-APIs der App laden. Die Widgets binden sich an die Datastores: Eine Tabelle zeigt die Zeilen eines Listen-Datastores, die Felder eines Formulars lesen und schreiben in einem Datensatz-Datastore.

Das ist das Bindeglied zwischen zwei Kapiteln: Die Tabellen-APIs werden über dem Datenmodell angelegt (Kapitel APIs & GraphQL); hier wird der Bildschirm an sie gebunden.

#Die zwei Arten von Datastore

Art	Was sie lädt	Wofür
Datensatz	EINEN Datensatz (oder einen neuen, leeren)	Formulare: Die Felder binden sich an die Felder des Datensatzes, und am Ende wird gespeichert.
Liste	Eine Sammlung von Datensätzen	Tabellen, Listen, Karten, Diagramme, Kanbans, Kalender.

Datastores können an zwei Orten leben:

• Auf dem Bildschirm — im Inspektor ohne Auswahl angelegt, in der Kategorie Daten. Sie sind geteilt: Mehrere Widgets können aus demselben lesen, und das ist es, was man für Formulare und für Master-Detail-Beziehungen verwendet.
• In einem Widget — die Daten-Widgets (Tabelle, Diagramm, KPI…) haben ihren eigenen Datastore in ihrer Kategorie Daten. Das ist der häufigste Fall für eigenständige Grids und Diagramme.

Die Maschinerie ist an beiden Orten dieselbe; der einzige Unterschied liegt in den Wertquellen, die in den Filtern verfügbar sind (siehe die Bindungen).

#Einen Datastore auf dem Bildschirm anlegen

1. Klicken Sie auf eine leere Zone des Canvas, damit der Inspektor den Bildschirm zeigt.
2. Klicken Sie in der Kategorie Daten auf + Datensatz oder + Liste.
3. Klicken Sie auf den angelegten Datastore, um das Modal Datastore konfigurieren zu öffnen.
4. Geben Sie ihm einen Name des Datastores — unter diesem Namen finden ihn die Widgets und der Code (z. B. conta, contas).
5. Wählen Sie unter Tabellen-API die API, die die Daten liefert. Die Felder der API stehen dann für Spalten, Bindungen und Filter zur Verfügung.

#Datensatz-Datastore — welcher Datensatz geladen wird

Ein Datensatz-Datastore antwortet auf eine Frage: welcher Datensatz? Die Antwort geben Sie unter Welcher Datensatz geladen wird (Schlüssel):

1. Klicken Sie auf + Schlüsselfeld.
2. Wählen Sie das Feld (standardmäßig der Primärschlüssel), den Operator und den Wert — typischerweise ein Param der Route: Der Bildschirm Kontodatenblatt erhält id in der Adresse und lädt das Konto mit dieser id.
3. Mehrere Bedingungen bilden einen zusammengesetzten Schlüssel — alle müssen passen.

Ohne Bedingungen lädt der Datastore einen neuen (leeren) Datensatz — so taugt derselbe Formularbildschirm auch zum Anlegen: ohne id geöffnet, beginnt er leer; gespeichert, macht er das Insert.

#Listen-Datastore — Filter und Laden

#Filter (where)

Die Filter (where) sind Bedingungen, die bei jedem Lesen der Daten gelten — hier wird begrenzt, was aus der Datenbank kommt. Jede Bedingung besteht aus Feld / Operator / Wert; + Filter hinzufügen ergänzt Bedingungen, und + Gruppe erzeugt verschachtelte Untergruppen, wobei Alle (AND) oder Beliebige (OR) entscheidet, wie sie sich verbinden.

Beispiel aus der Kundenverwaltung: Der Bildschirm Konten filtert estado eq "activa"; das Panel „meine Konten“ ergänzt gestor eq → Sitzung ▸ username.

#Laden und Seite

Option	Was sie tut
Alles laden	Holt alle Datensätze des Filters auf einmal — Blättern, Sortieren und Filtern auf dem Bildschirm wird sofort wirksam.
Seite für Seite	Geht bei jedem Seitenwechsel zum Server — für große Tabellen, bei denen alles zu holen keinen Sinn ergibt.
Pro Seite	Wie viele Zeilen auf dem Bildschirm gleichzeitig zu sehen sind — nicht zu verwechseln damit, wie viele Datensätze gelesen werden.
Automatisch laden	Die Daten lesen, sobald der Bildschirm geöffnet wird. Schalten Sie es aus, um erst nach einer Aktion zu laden (etwa einem Button „Suchen“).

#Die Bindungen — woher ein Wert kommt

Immer wenn ein Filter, ein Schlüssel oder eine Eigenschaft einen Wert braucht, verwenden Sie dasselbe Teil: die Bindung. Der erste Selektor nennt die Quelle; der Rest ändert sich mit ihr:

Quelle	Was sie ist
Fest	Ein Wert, der direkt dort eingetragen wird, gleich für alle.
Param	Ein Parameter der Route des Bildschirms (Abschnitt Routen-Parameter).
Sitzung	Ein Feld des angemeldeten Benutzers (userId, username, name).
Zustand	Ein Wert, der mit keplin.state.set() im Speicher der App abgelegt wird — auf jedem Bildschirm verfügbar.
Datastore	Ein Feld aus einem anderen Datastore des Bildschirms — die Grundlage von Master-Detail.
Widget	Der aktuelle Wert eines anderen Eingabe-Widgets — die Grundlage interaktiver Filter.

Die Quellen Datastore und Widget gibt es nur in den Datastores innerhalb von Widgets — sie hängen vom Rest des Bildschirms ab. In den Datastores des Bildschirms bleiben die ersten vier.

Mit diesen Teilen baut man die Alltagsmuster ohne Code:

• Master-Detail — die Opportunity-Tabelle des Kontos: im Datastore der Tabelle der Filter contaId eq → Datastore ▸ conta ▸ id. Ein anderes Konto auszuwählen lädt das Detail neu.
• Filter über Text — ein Textfeld „suchen“ und, im Datastore der Tabelle, nome contains → Widget ▸ das Textfeld. (Um erst beim Klick auf einen Button zu filtern, geht man über ein Ereignis — siehe Ereignisse und das SDK.)

#Formularfelder an einen Datensatz binden

Jedes Formularfeld hat in der Kategorie Daten den Abschnitt Datenbindung: Wählen Sie den Datensatz-Datastore und das Feld. Von da an zeigt die Eingabe den geladenen Wert, und die Änderungen bleiben im Datastore — ungespeichert — bis jemand speichert.

Der letzte Schritt ist ein Button, dessen Ereignis speichert:

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

Dieser Code ist genau das, was die vordefinierte Aktion Datastore speichern des Ereignis-Editors für Sie einfügt. save() validiert zuerst (Pflichtfelder, Regeln, Validierungsskripte) und speichert nur, wenn alles besteht; es gibt true zurück, wenn gespeichert wurde.

#Das Modal Datastore konfigurieren, Feld für Feld

Feld	Datensatz	Liste
Name des Datastores	✓	✓
Tabellen-API	✓	✓
Welcher Datensatz geladen wird (Schlüssel)	✓	—
Filter (where)	—	✓
Laden / Pro Seite	—	✓
Automatisch laden	✓	✓

#Datastores auf öffentlichen Bildschirmen

Auf einem als Öffentlicher Bildschirm (ohne Sitzung) markierten Bildschirm kommen die Daten ausschließlich aus APIs mit öffentlichem Lesezugriff: Der Selektor zeigt nur diese, und eine bereits gewählte API, die nicht öffentlich ist, wird gekennzeichnet — Diese API hat keinen öffentlichen Lesezugriff — auf einem Bildschirm ohne Sitzung lädt sie keine Daten. Der Lesezugriff wird im API-Editor als öffentlich markiert.

#Die Daten im Code

Alles, was die Datastores tun, steht auch im SDK der Ereignisse — keplin.data.store("name") gibt den Datastore über seinen Namen zurück, mit reload(), setWhere(), get()/set()/save() und Gefährten. Das Kapitel Ereignisse und das SDK geht es durch.

#Warum nicht…?

• Warum lädt es keine Daten? Prüfen Sie in dieser Reihenfolge: Ist Automatisch laden eingeschaltet? Existiert die gewählte API und ist sie veröffentlicht? Ist auf einem öffentlichen Bildschirm der Lesezugriff der API öffentlich? Schließt der Filter nicht alles aus?
• Warum öffnet sich immer ein leerer Datensatz? Der Datensatz-Datastore hat keine Bedingungen unter Welcher Datensatz geladen wird (Schlüssel) — oder der in der Bedingung verwendete Parameter kommt in der Route nicht an.
• Warum erscheint die neue Spalte nicht, nachdem ich das Modell geändert habe? Der Datastore hält ein Abbild der Felder der API von dem Moment, in dem Sie sie gewählt haben. Öffnen Sie Datastore konfigurieren erneut und wählen Sie die API neu, um das Abbild zu aktualisieren.
• Warum ist die Paginierung langsam? Sie sind in Seite für Seite mit vielen Gängen zum Server — oder in Alles laden ohne Filter in einer riesigen Tabelle. Passen Sie den Modus an die echte Größe der Daten an.