Datastores et données

Un écran ne parle pas directement à la base de données : il parle à des datastores — des conteneurs de données de l'écran qui chargent des enregistrements à travers les APIs de table de l'app. Les widgets se lient aux datastores : une Table affiche les lignes d'un datastore de liste, les champs d'un formulaire lisent et écrivent dans un datastore d'enregistrement.

C'est le maillon entre deux chapitres : les APIs de table se créent sur le modèle de données (chapitre APIs & GraphQL) ; ici on y relie l'écran.

#Les deux types de datastore

Type	Ce qu'il charge	Pour quoi
Enregistrement	UN enregistrement (ou un nouvel enregistrement, vide)	Les formulaires : les champs se lient aux champs de l'enregistrement, et à la fin on enregistre.
Liste	Une collection d'enregistrements	Tables, listes, cartes, graphiques, kanbans, calendriers.

Les datastores peuvent vivre à deux endroits :

• Sur l'écran — créés dans l'inspecteur sans sélection, dans la catégorie Données. Ils sont partagés : plusieurs widgets peuvent lire le même, et c'est ce qu'on utilise pour les formulaires et pour les relations maître-détail.
• Dans un widget — les widgets de données (Table, Graphique, KPI…) ont leur propre datastore dans leur catégorie Données. C'est le cas le plus courant pour des grilles et des graphiques indépendants.

Le moteur est le même aux deux endroits ; la seule différence tient aux sources de valeur disponibles dans les filtres (voir les liaisons).

#Créer un datastore sur l'écran

1. Cliquez sur une zone vide du canvas pour que l'inspecteur montre l'écran.
2. Dans la catégorie Données, cliquez sur + enregistrement ou + liste.
3. Cliquez sur le datastore créé pour ouvrir la fenêtre Configurer le datastore.
4. Donnez-lui un Nom du datastore — c'est par ce nom que les widgets et le code le trouvent (ex. : conta, contas).
5. Dans API de table, choisissez l'API qui sert les données. Les champs de l'API deviennent disponibles pour les colonnes, les liaisons et les filtres.

#Datastore d'enregistrement — quel enregistrement charger

Un datastore d'enregistrement répond à une question : quel enregistrement ? La réponse se donne dans Quel enregistrement charger (clé) :

1. Cliquez sur + champ de la clé.
2. Choisissez le champ (par défaut, la clé primaire), l'opérateur et la valeur — typiquement un Param de la route : l'écran Fiche de Compte reçoit id dans l'adresse et charge le compte portant cet id.
3. Plusieurs conditions forment une clé composée — toutes doivent correspondre.

Sans conditions, le datastore charge un nouvel enregistrement (vide) — c'est ainsi que le même écran de formulaire sert à créer : ouvert sans id, il commence vierge ; enregistré, il fait l'insertion.

#Datastore de liste — filtres et chargement

#Filtres (where)

Les Filtres (where) sont des conditions appliquées chaque fois que les données sont lues — c'est ici qu'on limite ce qui vient de la base de données. Chaque condition est champ / opérateur / valeur ; + ajouter un filtre ajoute des conditions et + groupe crée des sous-groupes imbriqués, avec Toutes (AND) ou Au moins une (OR) pour décider comment ils se combinent.

Exemple de Gestion des Clients : l'écran Comptes filtre estado eq "activa" ; le panneau « mes comptes » ajoute gestor eq → Session ▸ username.

#Chargement et page

Option	Ce qu'elle fait
Tout charger	Ramène tous les enregistrements du filtre d'un coup — changer de page, trier et filtrer à l'écran devient instantané.
Une page à la fois	Interroge le serveur à chaque changement de page — pour les grandes tables, où tout ramener n'a pas de sens.
Par page	Combien de lignes sont visibles à la fois à l'écran — à ne pas confondre avec le nombre d'enregistrements lus.
Charger automatiquement	Lire les données dès l'ouverture de l'écran. Désactivez si vous préférez ne charger qu'après une action (un bouton « Rechercher », par exemple).

#Les liaisons — d'où vient une valeur

Chaque fois qu'un filtre, une clé ou une propriété a besoin d'une valeur, vous utilisez la même pièce : la liaison. Le premier sélecteur dit la source ; le reste change selon elle :

Source	Ce que c'est
Fixe	Une valeur saisie sur place, la même pour tout le monde.
Param	Un paramètre de la route de l'écran (section Paramètres de route).
Session	Un champ de l'utilisateur connecté (userId, username, name).
État	Une valeur conservée dans la mémoire de l'app avec keplin.state.set() — disponible sur tous les écrans.
Datastore	Un champ d'un autre datastore de l'écran — la base du maître-détail.
Widget	La valeur actuelle d'un autre widget de saisie — la base des filtres interactifs.

Les sources Datastore et Widget n'existent que dans les datastores à l'intérieur de widgets — elles dépendent du reste de l'écran. Dans les datastores de l'écran, il ne reste que les quatre premières.

Avec ces pièces, on monte les schémas du quotidien sans code :

• Maître-détail — la table d'opportunités du compte : dans le datastore de la table, filtre contaId eq → Datastore ▸ conta ▸ id. Sélectionner un autre compte recharge le détail.
• Filtre par texte — un Champ de texte « rechercher » et, dans le datastore de la table, nome contains → Widget ▸ le champ. (Pour ne filtrer qu'au clic sur un bouton, cela se fait par événement — voir Événements et le SDK.)

#Relier des champs de formulaire à un enregistrement

Chaque champ de formulaire a, dans la catégorie Données, la section Liaison de données : choisissez le datastore d'enregistrement et le champ. À partir de là, le champ de saisie affiche la valeur chargée et les modifications restent dans le datastore — non enregistrées — jusqu'à ce que quelqu'un enregistre.

L'étape finale est un bouton dont l'événement enregistre :

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

Ce code est exactement ce que l'action prédéfinie Enregistrer le datastore de l'éditeur d'événements insère pour vous. save() valide d'abord (obligatoires, règles, scripts de validation) et n'enregistre que si tout passe ; il renvoie true s'il a enregistré.

#La fenêtre Configurer le datastore, champ par champ

Champ	Enregistrement	Liste
Nom du datastore	✓	✓
API de table	✓	✓
Quel enregistrement charger (clé)	✓	—
Filtres (where)	—	✓
Chargement / Par page	—	✓
Charger automatiquement	✓	✓

#Datastores sur des écrans publics

Sur un écran marqué Écran public (sans session), les données viennent uniquement d'APIs avec lecture publique : le sélecteur ne montre que celles-là, et une API déjà choisie qui ne serait pas publique est signalée — Cette API n'a pas de lecture publique — sur un écran sans session, elle ne charge pas de données. La lecture se marque comme publique dans l'éditeur de l'API.

#Les données dans le code

Tout ce que font les datastores est aussi dans le SDK des événements — keplin.data.store("nom") renvoie le datastore par son nom, avec reload(), setWhere(), get()/set()/save() et compagnie. Le chapitre Événements et le SDK le parcourt.

#Pourquoi ne… ?

• Pourquoi cela ne charge-t-il pas de données ? Regardez, dans l'ordre : Charger automatiquement est-il activé ? L'API choisie existe-t-elle et est-elle publiée ? Sur un écran public, la lecture de l'API est-elle publique ? Le filtre n'est-il pas en train de tout exclure ?
• Pourquoi cela ouvre-t-il toujours un enregistrement vide ? Le datastore d'enregistrement n'a pas de conditions dans Quel enregistrement charger (clé) — ou le paramètre utilisé dans la condition n'arrive pas dans la route.
• Pourquoi ai-je changé le modèle et la nouvelle colonne n'apparaît pas ? Le datastore conserve un instantané des champs de l'API du moment où vous l'avez choisie. Rouvrez Configurer le datastore et rechoisissez l'API pour actualiser l'instantané.
• Pourquoi la pagination est-elle lente ? Vous êtes en Une page à la fois avec beaucoup d'allers-retours au serveur — ou en Tout charger sans filtres sur une table énorme. Ajustez le mode à la taille réelle des données.