The screens

This is the longest stage of the guide, and the one that gives the app its face. By the end you have four screens designed and working on top of the model's real data: an Início with indicators and a chart, a list of Contas, a Ficha de Conta that saves, and an Oportunidades board with draggable cards.

Before the screens, though, there is a short step that makes them possible.

#First the table APIs

A screen does not talk to the database. It talks to datastores — each screen's data containers — and the datastores read and write through the app's table APIs. A table API points at an entity of the model and generates, on its own, the read and write operations.

Let's create three, one per entity:

1. Choose the Code panel in the sidebar.
2. On the APIs row, click the + (New API).
3. In Name, type contas. The name is the base of the operations (getContas, addContas, updateContas, deleteContas) — so do not give it prefixes like get or listar.
4. Click Create API. The builder opens on the Build tab.
5. In the Pipeline section, choose the Table block.
6. In the Table field, choose Dados CRM ▸ Contas.
7. In Exposed actions, leave Select, Insert, Update and Delete checked — the CRM needs all four.
8. Leave Public access (no session) entirely off: this app is for people who are signed in.
9. In Included fields, confirm that the fields the screens will use are checked. For the accounts, that is all of them.
10. Turn on the Published switch and click Save.

Repeat for the other two:

API	Entity	Actions	Notes
contas	Contas	Select, Insert, Update, Delete	All the fields.
contactos	Contactos	Select, Insert, Update, Delete	Includes the conta navigator (only the nome field).
oportunidades	Oportunidades	Select, Insert, Update, Delete	Includes the conta navigator (only the nome field).

The navigators are what lets you show the account's name next to an opportunity without writing a line of SQL: check them in the list of included fields, and the conta.nome field becomes available in the screens.

#Creating the four screens

The screens live in the UI panel, in the Screens section.

1. Choose the UI panel in the sidebar.
2. On the Screens row, click the New screen button.
3. Type the name and confirm with Create. The screen opens right away in the workspace.

Create all four at once, in this order:

Screen name	Route	What it is going to be
Início	/inicio	The sales dashboard, with indicators and chart.
Contas	/contas	The list of accounts.
Ficha de Conta	/ficha-de-conta	The form of one account.
Oportunidades	/oportunidades	The kanban board.

The Route is derived from the name and is seen (and edited) in the inspector, when no widget is selected. Leave them as they are — the guide refers to them further along.

#The Início screen — the sales dashboard

Open the Início screen. The design has four pieces: a title, a strip of indicators, a chart and a table.

#The title

1. Drag a Label from the palette to the top of the canvas.
2. In the Content category of the inspector, type the text Painel comercial.
3. In the Appearance category, raise the Size of the text — it is the page title.

#The strip of indicators

Four numbers side by side are made with one KPI widget of four indicators, not with four widgets: the alignment and the spacing come guaranteed.

1. Drag a KPI below the title and stretch it across the full width.
2. In the Data category, the Indicators section starts with one. Use Add indicator until you have four.
3. Each indicator has a Label, an icon, an Own dataset (its datastore) and a value with an Aggregation.

Configure them like this:

Label	Datastore (table API)	Filter	Value
Contas ativas	contas	—	Count of id
Oportunidades abertas	oportunidades	fase ≠ fechada_ganha and fase ≠ fechada_perdida	Count of id
Valor em pipeline	oportunidades	the same filter	Sum of valor
Fechado este trimestre	oportunidades	fase = fechada_ganha	Sum of valor

On the two money indicators, open the Format and choose currency EUR with zero decimals — 475,850 reads better than 475850.

#The chart

1. Drag a Chart to the left half, below the KPI.
2. In the Data category, create the list datastore on the oportunidades API.
3. In Chart type, choose Bars.
4. In Category field (X axis / slices), choose fase.
5. In Value fields, add valor.
6. In the Appearance category, turn on Show title and type Pipeline por fase.

#The upcoming closes table

1. Drag a Table to the right half, next to the chart.
2. In the Data category, create the list datastore on oportunidades, with the open-stages filter (the same one as the indicators), sorted by data_fecho ascending and Per page at 8.
3. In the Data category, Columns section, define four columns:

Field	Header
titulo	Oportunidade
conta.nome	Conta
valor	Valor (€)
data_fecho	Fecho

4. Turn on Show title and type Próximos fechos.

#The Contas screen — the list

Open the Contas screen. It is three widgets.

1. A Label at the top, with the text Contas.
2. A Button in the top right corner: in the Content category, text Nova conta and icon plus.
3. A Table taking up the rest of the screen. In the Data category, create the list datastore on the contas API, sorted by nome ascending, and define the columns:

Field	Header
nome	Nome
sector	Sector
cidade	Cidade
telefone	Telefone
email	Email
estado	Estado

What is left is wiring up the two gestures that make this list serve for something. Both are written in the Events category, in TypeScript:

On the Button, in the onClick event — open the blank form, to create:

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

On the Table, in the onRowClick event — open the form of the clicked row:

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

#The Ficha de Conta screen — the form

This is the screen with the most pieces, and the one that best shows how the data works. Open the Ficha de Conta screen.

#The route parameter

1. Click an empty area of the canvas — the inspector switches to showing the screen.
2. In the Route parameters section, click + add parameter and type id.
3. Leave Required off. This is deliberate: without id the screen opens blank, and that is how the same form serves to create a new account.

The Route becomes /ficha-de-conta/:id.

#The screen's two datastores

Still with the screen selected, in the Data category:

1. Click + record. Click the created datastore to open the Configure datastore modal.
2. In Datastore name, type conta.
3. In Table API, choose contas.
4. In Which record to load (key), click + key field and build the condition: field id, operator eq, value Param ▸ id.
5. Leave Load automatically on and close with Done.

Now the second one, for the account's contacts:

1. Click + list and open it.
2. Name contactosConta, Table API contactos.
3. In Filters (where), add: field conta_id, operator eq, value Param ▸ id.
4. Sort by nome ascending.

#The form

1. Drag a Panel to the left of the canvas. In the Appearance category, turn on Show title and type Dados da empresa.
2. Drag the Textboxes into the panel — dropping a widget inside a panel makes it its child. For each one, in the Content category type the label and, in the Data category, Data binding section, choose the conta datastore and the field:

Label	Field	Required
Nome	nome	yes
NIF	nif	no
Sector	sector	no
Cidade	cidade	no
Telefone	telefone	no
Email	email	no

3. For the status, use a Dropdown instead of a textbox: label Estado, bound to conta ▸ estado, Required on, and static options:

Value	Label
ativo	Ativo
prospeto	Prospeto
inativo	Inativo

4. Drag a Table to the right of the panel, bound to the contactosConta datastore, with the columns nome (Nome), cargo (Cargo) and telefone (Telefone), and the title Contactos desta conta.

#Saving and going back

Two Buttons below the panel, each with its onClick event:

Save (icon save):

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

Back (icon arrow-left):

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

save() validates first — required fields and rules — and only saves if everything passes; it returns true when it saved. That is why the notice and the navigation live inside the if.

#The Oportunidades screen — the kanban board

Open the Oportunidades screen.

1. A Label at the top, with the text Oportunidades.
2. Drag a Kanban below it, across the full width.
3. In the Data category, create the list datastore on the oportunidades API (no filter — the board shows everything), with Per page at 50.
4. In Status field (column), choose fase. It is this field that says which column each card lives in — and it is what gets written when someone drags a card.
5. In Columns source, choose Static and use + add column six times:

Value	Label	Color
prospecao	Prospeção	grey
qualificacao	Qualificação	blue
proposta	Proposta	amber
negociacao	Negociação	purple
fechada_ganha	Ganha	green
fechada_perdida	Perdida	red

6. Turn on Allow dragging cards and Card count; leave Uncategorized column off.
7. In Card template, say what each card shows:

Field	Role
titulo	Title
conta.nome	Caption
valor	Value

8. Below the board, add a Table with the title Todas as oportunidades, bound to a list datastore on oportunidades, with the columns titulo, conta.nome, valor, fase, data_fecho and responsavel.

#Seeing the result

There is no save button on the screens: changes save themselves, and the top right corner says where they stand (Saving…, Saved).

To see the screen for real, click Preview: the platform saves whatever is pending and opens the screen in the real app, in a new browser tab. You go through the login like any user — the accounts that sign in to the app are created in the Publish and use stage, and until then you can use whichever one already exists.

#Why doesn't…?

• Why doesn't my API appear in the list of datastores? The API is a draft. Open it and turn on Published.
• Why does an empty form always open? The record datastore has no conditions in Which record to load (key), or the id parameter is not arriving on the route. Confirm that the route is /ficha-de-conta/:id.
• Why can't I see the conta.nome column? The navigator is not among the table API's Included fields — or the datastore was configured before you checked it. Reopen Configure datastore and pick the API again to refresh the portrait of the fields.
• Why won't the kanban let me drag? The datastore is missing the primary key, or the table API the Update action.
• Why is the chart empty? The Category field or the Value fields are not chosen — or the datastore's filter lets no row through.

The screens exist, but there is still no way to jump between them. Next stage: navigation and theme.