Les écrans

C'est l'étape la plus longue du guide, et celle qui donne un visage à l'app. À la fin, vous avez quatre écrans dessinés et fonctionnels sur les vraies données du modèle : un Início avec des indicateurs et un graphique, une liste de Contas, une Ficha de Conta qui enregistre, et un tableau d'Oportunidades avec des cartes que l'on fait glisser.

Avant les écrans, cependant, il y a une courte étape qui les rend possibles.

#D'abord les APIs de table

Un écran ne parle pas à la base de données. Il parle à des datastores — les conteneurs de données de chaque écran — et les datastores lisent et écrivent à travers les APIs de table de l'app. Une API de table pointe vers une entité du modèle et génère toute seule les opérations de lecture et d'écriture.

Nous allons en créer trois, une par entité :

1. Choisissez le panneau Code dans la barre latérale.
2. Sur la ligne APIs, cliquez sur le + (Nouvelle API).
3. Dans Nom, écrivez contas. Le nom est la base des opérations (getContas, addContas, updateContas, deleteContas) — ne lui mettez donc pas de préfixes comme get ou listar.
4. Cliquez sur Créer une API. Le constructeur s'ouvre sur l'onglet Construire.
5. Dans la section Pipeline, choisissez le bloc Table.
6. Dans le champ Table, choisissez Dados CRM ▸ Contas.
7. Dans Actions exposées, laissez Select, Insert, Update et Delete cochés — le CRM a besoin des quatre.
8. Laissez Accès public (sans session) entièrement désactivé : cette app est faite pour des gens qui ont ouvert une session.
9. Dans Champs inclus, vérifiez que les champs que les écrans vont utiliser sont cochés. Pour les comptes, ce sont tous.
10. Activez l'interrupteur Publiée et cliquez sur Enregistrer.

Répétez pour les deux autres :

API	Entité	Actions	Notes
contas	Contas	Select, Insert, Update, Delete	Tous les champs.
contactos	Contactos	Select, Insert, Update, Delete	Inclut le navigator conta (seulement le champ nome).
oportunidades	Oportunidades	Select, Insert, Update, Delete	Inclut le navigator conta (seulement le champ nome).

Les Navigators sont ce qui permet d'afficher le nom du compte à côté d'une opportunité sans écrire une ligne de SQL : cochez-les dans la liste des champs inclus, et le champ conta.nome devient disponible dans les écrans.

#Créer les quatre écrans

Les écrans vivent dans le panneau UI, dans la section Écrans.

1. Choisissez le panneau UI dans la barre latérale.
2. Sur la ligne Écrans, cliquez sur le bouton Nouvel écran.
3. Écrivez le nom et confirmez avec Créer. L'écran s'ouvre aussitôt dans l'espace de travail.

Créez les quatre d'un coup, dans cet ordre :

Nom de l'écran	Route	Ce que ce sera
Início	/inicio	Le tableau de bord commercial, avec indicateurs et graphique.
Contas	/contas	La liste des comptes.
Ficha de Conta	/ficha-de-conta	Le formulaire d'un compte.
Oportunidades	/oportunidades	Le tableau kanban.

La Route est dérivée du nom et se voit (et se modifie) dans l'inspecteur, quand aucun widget n'est sélectionné. Laissez-les telles quelles — le guide s'y réfère plus loin.

#L'écran Início — le tableau de bord commercial

Ouvrez l'écran Início. Le design a quatre pièces : un titre, une bande d'indicateurs, un graphique et une table.

#Le titre

1. Faites glisser un Libellé de la palette vers le haut du canvas.
2. Dans la catégorie Contenu de l'inspecteur, écrivez le texte Painel comercial.
3. Dans la catégorie Apparence, augmentez la Taille du texte — c'est le titre de la page.

#La bande d'indicateurs

Quatre nombres côte à côte se font avec un widget KPI à quatre indicateurs, pas avec quatre widgets : l'alignement et l'espacement sont garantis.

1. Faites glisser un KPI sous le titre et étirez-le sur toute la largeur.
2. Dans la catégorie Données, la section Indicateurs commence avec un seul. Utilisez Ajouter un indicateur jusqu'à en avoir quatre.
3. Chaque indicateur a un Libellé, une icône, un Jeu de données dédié (son datastore) et une valeur avec une Agrégation.

Configurez-les ainsi :

Libellé	Datastore (API de table)	Filtre	Valeur
Contas ativas	contas	—	Comptage de id
Oportunidades abertas	oportunidades	fase ≠ fechada_ganha et fase ≠ fechada_perdida	Comptage de id
Valor em pipeline	oportunidades	le même filtre	Somme de valor
Fechado este trimestre	oportunidades	fase = fechada_ganha	Somme de valor

Sur les deux indicateurs monétaires, ouvrez le Format et choisissez la devise EUR avec zéro décimale — 475 850 se lit mieux que 475850.

#Le graphique

1. Faites glisser un Graphique sur la moitié gauche, sous le KPI.
2. Dans la catégorie Données, créez le datastore de liste sur l'API oportunidades.
3. Dans Type de graphique, choisissez Barres.
4. Dans Champ de catégorie (axe X / parts), choisissez fase.
5. Dans Champs de valeur, ajoutez valor.
6. Dans la catégorie Apparence, activez Afficher le titre et écrivez Pipeline por fase.

#La table des prochaines clôtures

1. Faites glisser une Table sur la moitié droite, à côté du graphique.
2. Dans la catégorie Données, créez le datastore de liste sur oportunidades, avec le filtre des phases ouvertes (le même que celui des indicateurs), trié par data_fecho croissant et Par page à 8.
3. Dans la catégorie Données, section Colonnes, définissez quatre colonnes :

Champ	En-tête
titulo	Oportunidade
conta.nome	Conta
valor	Valor (€)
data_fecho	Fecho

4. Activez Afficher le titre et écrivez Próximos fechos.

#L'écran Contas — la liste

Ouvrez l'écran Contas. Ce sont trois widgets.

1. Un Libellé en haut, avec le texte Contas.
2. Un Bouton dans le coin supérieur droit : dans la catégorie Contenu, texte Nova conta et icône plus.
3. Une Table occupant le reste de l'écran. Dans la catégorie Données, créez le datastore de liste sur l'API contas, trié par nome croissant, et définissez les colonnes :

Champ	En-tête
nome	Nome
sector	Sector
cidade	Cidade
telefone	Telefone
email	Email
estado	Estado

Il reste à brancher les deux gestes qui font que cette liste sert à quelque chose. Tous deux s'écrivent dans la catégorie Événements, en TypeScript :

Sur le Bouton, dans l'événement onClick — ouvrir la fiche vierge, pour créer :

keplin.nav.go("/ficha-de-conta");

Sur la Table, dans l'événement onRowClick — ouvrir la fiche de la ligne cliquée :

keplin.nav.go("/ficha-de-conta/" + keplin.event.row.id);

#L'écran Ficha de Conta — le formulaire

C'est l'écran qui a le plus de pièces, et celui qui montre le mieux comment les données fonctionnent. Ouvrez l'écran Ficha de Conta.

#Le paramètre de la route

1. Cliquez sur une zone vide du canvas — l'inspecteur affiche alors l'écran.
2. Dans la section Paramètres de route, cliquez sur + ajouter un paramètre et écrivez id.
3. Laissez Obligatoire désactivé. C'est délibéré : sans id l'écran s'ouvre vierge, et c'est ainsi que le même formulaire sert à créer un nouveau compte.

La Route devient /ficha-de-conta/:id.

#Les deux datastores de l'écran

Toujours avec l'écran sélectionné, dans la catégorie Données :

1. Cliquez sur + enregistrement. Cliquez sur le datastore créé pour ouvrir la fenêtre Configurer le datastore.
2. Dans Nom du datastore, écrivez conta.
3. Dans API de table, choisissez contas.
4. Dans Quel enregistrement charger (clé), cliquez sur + champ de la clé et montez la condition : champ id, opérateur eq, valeur Param ▸ id.
5. Laissez Charger automatiquement activé et fermez avec Terminé.

Maintenant le second, pour les contacts du compte :

1. Cliquez sur + liste et ouvrez-le.
2. Nom contactosConta, API de table contactos.
3. Dans Filtres (where), ajoutez : champ conta_id, opérateur eq, valeur Param ▸ id.
4. Triez par nome croissant.

#Le formulaire

1. Faites glisser un Panneau vers la gauche du canvas. Dans la catégorie Apparence, activez Afficher le titre et écrivez Dados da empresa.
2. Faites glisser les Champs de texte à l'intérieur du panneau — lâcher un widget dans un panneau en fait son enfant. Pour chacun, dans la catégorie Contenu écrivez le libellé et, dans la catégorie Données, section Liaison de données, choisissez le datastore conta et le champ :

Libellé	Champ	Obligatoire
Nome	nome	oui
NIF	nif	non
Sector	sector	non
Cidade	cidade	non
Telefone	telefone	non
Email	email	non

3. Pour l'état, utilisez une Liste plutôt qu'un champ de texte : libellé Estado, relié à conta ▸ estado, Obligatoire activé, et options statiques :

Valeur	Libellé
ativo	Ativo
prospeto	Prospeto
inativo	Inativo

4. Faites glisser une Table à droite du panneau, reliée au datastore contactosConta, avec les colonnes nome (Nome), cargo (Cargo) et telefone (Telefone), et le titre Contactos desta conta.

#Enregistrer et revenir

Deux Boutons sous le panneau, avec leur événement onClick respectif :

Enregistrer (icône save) :

const ok = await keplin.data.store("conta").save();
if (ok) {
  keplin.ui.toast("Compte enregistré");
  keplin.nav.go("/contas");
}

Revenir (icône arrow-left) :

keplin.nav.go("/contas");

save() valide d'abord — obligatoires et règles — et n'enregistre que si tout passe ; il renvoie true quand l'enregistrement a eu lieu. C'est pour cela que l'avertissement et la navigation sont à l'intérieur du if.

#L'écran Oportunidades — le tableau kanban

Ouvrez l'écran Oportunidades.

1. Un Libellé en haut, avec le texte Oportunidades.
2. Faites glisser un Kanban en dessous, sur toute la largeur.
3. Dans la catégorie Données, créez le datastore de liste sur l'API oportunidades (sans filtre — le tableau montre tout), avec Par page à
4. Dans Champ d'état (colonne), choisissez fase. C'est ce champ qui dit dans quelle colonne vit chaque carte — et c'est lui qui est écrit quand quelqu'un fait glisser une carte.
5. Dans Source des colonnes, choisissez Statique et utilisez + ajouter une colonne six fois :

Valeur	Libellé	Couleur
prospecao	Prospeção	gris
qualificacao	Qualificação	bleu
proposta	Proposta	ambre
negociacao	Negociação	violet
fechada_ganha	Ganha	vert
fechada_perdida	Perdida	rouge

6. Activez Autoriser le glisser-déposer des cartes et Nombre de cartes ; laissez Colonne pour les non catégorisés désactivée.
7. Dans Template de la carte, dites ce que chaque carte affiche :

Champ	Rôle
titulo	Titre
conta.nome	Légende
valor	Valeur

8. Sous le tableau, ajoutez une Table avec le titre Todas as oportunidades, reliée à un datastore de liste sur oportunidades, avec les colonnes titulo, conta.nome, valor, fase, data_fecho et responsavel.

#Voir le résultat

Il n'y a pas de bouton d'enregistrement dans les écrans : les modifications s'enregistrent toutes seules, et le coin supérieur droit dit où elles en sont (Enregistrement…, Enregistré).

Pour voir l'écran pour de vrai, cliquez sur Prévisualiser : la plateforme enregistre ce qui est en attente et ouvre l'écran dans l'app réelle, dans un nouvel onglet du navigateur. Vous passez par la connexion comme n'importe quel utilisateur — les comptes qui entrent dans l'app se créent à l'étape Publier et utiliser, et d'ici là vous pouvez utiliser celui qui existe déjà.

#Pourquoi pas… ?

• Pourquoi mon API n'apparaît-elle pas dans la liste des datastores ? L'API est en brouillon. Ouvrez-la et activez Publiée.
• Pourquoi une fiche vide s'ouvre-t-elle toujours ? Le datastore d'enregistrement n'a pas de conditions dans Quel enregistrement charger (clé), ou le paramètre id n'arrive pas par la route. Vérifiez que la route est /ficha-de-conta/:id.
• Pourquoi je ne vois pas la colonne conta.nome ? Le navigator n'est pas inclus dans les Champs inclus de l'API de table — ou le datastore a été configuré avant que vous ne le cochiez. Rouvrez Configurer le datastore et choisissez à nouveau l'API pour rafraîchir le portrait des champs.
• Pourquoi le kanban ne laisse-t-il pas glisser ? Il manque la clé primaire dans le datastore, ou l'action Update dans l'API de table.
• Pourquoi le graphique est-il vide ? Le Champ de catégorie ou les Champs de valeur ne sont pas choisis — ou le filtre du datastore ne laisse passer aucune ligne.

Les écrans existent, mais il n'y a pas encore moyen de sauter de l'un à l'autre. Prochaine étape : navigation et thème.