Os ecrãs

Esta é a etapa mais longa do guia, e a que dá cara à app. No fim tens quatro ecrãs desenhados e a funcionar sobre os dados verdadeiros do modelo: um Início com indicadores e um gráfico, uma lista de Contas, uma Ficha de Conta que grava, e um quadro de Oportunidades com cartões arrastáveis.

Antes dos ecrãs, porém, há um passo curto que os torna possíveis.

#Primeiro as APIs de tabela

Um ecrã não fala com a base de dados. Fala com datastores — os contentores de dados de cada ecrã — e os datastores leem e escrevem através das APIs de tabela da app. Uma API de tabela aponta a uma entidade do modelo e gera, sozinha, as operações de leitura e escrita.

Vamos criar três, uma por entidade:

1. Escolhe o painel Código na barra lateral.
2. Na linha APIs, clica no + (Nova API).
3. Em Nome, escreve contas. O nome é a base das operações (getContas, addContas, updateContas, deleteContas) — por isso não lhe ponhas prefixos como get ou listar.
4. Clica em Criar API. O construtor abre no separador Construir.
5. Na secção Pipeline, escolhe o bloco Tabela.
6. No campo Tabela, escolhe Dados CRM ▸ Contas.
7. Em Acções expostas, deixa Select, Insert, Update e Delete marcados — o CRM precisa dos quatro.
8. Deixa Acesso público (sem sessão) todo desligado: esta app é para quem tem sessão iniciada.
9. Em Campos incluídos, confirma que estão marcados os campos que os ecrãs vão usar. Para as contas, são todos.
10. Liga o interruptor Publicada e clica em Gravar.

Repete para as outras duas:

API	Entidade	Acções	Notas
contas	Contas	Select, Insert, Update, Delete	Todos os campos.
contactos	Contactos	Select, Insert, Update, Delete	Inclui o navigator conta (só o campo nome).
oportunidades	Oportunidades	Select, Insert, Update, Delete	Inclui o navigator conta (só o campo nome).

Os navigators são o que permite mostrar o nome da conta ao lado de uma oportunidade sem escrever uma linha de SQL: marca-os na lista de campos incluídos, e o campo conta.nome passa a estar disponível nos ecrãs.

#Criar os quatro ecrãs

Os ecrãs vivem no painel UI, na secção Ecrãs.

1. Escolhe o painel UI na barra lateral.
2. Na linha Ecrãs, clica no botão Novo ecrã.
3. Escreve o nome e confirma em Criar. O ecrã abre logo no espaço de trabalho.

Cria os quatro de uma vez, por esta ordem:

Nome do ecrã	Rota	O que vai ser
Início	/inicio	O painel comercial, com indicadores e gráfico.
Contas	/contas	A lista de contas.
Ficha de Conta	/ficha-de-conta	O formulário de uma conta.
Oportunidades	/oportunidades	O quadro kanban.

A Rota é derivada do nome e vê-se (e edita-se) no inspector, quando nenhum widget está seleccionado. Deixa-as como estão — o guia refere-se a elas mais à frente.

#O ecrã Início — o painel comercial

Abre o ecrã Início. O desenho tem quatro peças: um título, uma faixa de indicadores, um gráfico e uma tabela.

#O título

1. Arrasta uma Etiqueta da palette para o topo do canvas.
2. Na categoria Conteúdo do inspector, escreve o texto Painel comercial.
3. Na categoria Aspecto, sobe o Tamanho do texto — é o título da página.

#A faixa de indicadores

Quatro números lado a lado fazem-se com um widget KPI de quatro indicadores, não com quatro widgets: o alinhamento e o espaçamento ficam garantidos.

1. Arrasta um KPI para baixo do título e estica-o a toda a largura.
2. Na categoria Dados, a secção Indicadores começa com um. Usa Acrescentar indicador até teres quatro.
3. Cada indicador tem um Rótulo, um ícone, um Conjunto de dados próprio (o datastore dele) e um valor com Agregação.

Configura-os assim:

Rótulo	Datastore (API de tabela)	Filtro	Valor
Contas ativas	contas	—	Contagem de id
Oportunidades abertas	oportunidades	fase ≠ fechada_ganha e fase ≠ fechada_perdida	Contagem de id
Valor em pipeline	oportunidades	o mesmo filtro	Soma de valor
Fechado este trimestre	oportunidades	fase = fechada_ganha	Soma de valor

Nos dois indicadores de dinheiro, abre o Formato e escolhe moeda EUR com zero decimais — 475.850 lê-se melhor do que 475850.

#O gráfico

1. Arrasta um Gráfico para a metade esquerda, por baixo do KPI.
2. Na categoria Dados, cria o datastore de lista sobre a API oportunidades.
3. Em Tipo de gráfico, escolhe Barras.
4. Em Campo de categoria (eixo X / fatias), escolhe fase.
5. Em Campos de valor, acrescenta valor.
6. Na categoria Aspecto, liga Mostrar título e escreve Pipeline por fase.

#A tabela de próximos fechos

1. Arrasta uma Tabela para a metade direita, ao lado do gráfico.
2. Na categoria Dados, cria o datastore de lista sobre oportunidades, com o filtro das fases abertas (o mesmo dos indicadores), ordenado por data_fecho ascendente e Por página a
3. Na categoria Dados, secção Colunas, define quatro colunas:

Campo	Cabeçalho
titulo	Oportunidade
conta.nome	Conta
valor	Valor (€)
data_fecho	Fecho

4. Liga Mostrar título e escreve Próximos fechos.

#O ecrã Contas — a lista

Abre o ecrã Contas. São três widgets.

1. Uma Etiqueta no topo, com o texto Contas.
2. Um Botão no canto superior direito: na categoria Conteúdo, texto Nova conta e ícone plus.
3. Uma Tabela ocupando o resto do ecrã. Na categoria Dados, cria o datastore de lista sobre a API contas, ordenado por nome ascendente, e define as colunas:

Campo	Cabeçalho
nome	Nome
sector	Sector
cidade	Cidade
telefone	Telefone
email	Email
estado	Estado

Falta ligar os dois gestos que fazem esta lista servir para alguma coisa. Ambos se escrevem na categoria Eventos, em TypeScript:

No Botão, no evento onClick — abrir a ficha em branco, para criar:

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

Na Tabela, no evento onRowClick — abrir a ficha da linha clicada:

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

#O ecrã Ficha de Conta — o formulário

Este é o ecrã com mais peças, e o que mostra melhor como os dados funcionam. Abre o ecrã Ficha de Conta.

#O parâmetro da rota

1. Clica numa zona vazia do canvas — o inspector passa a mostrar o ecrã.
2. Na secção Parâmetros de rota, clica em + adicionar parâmetro e escreve id.
3. Deixa Obrigatório desligado. Isto é deliberado: sem id o ecrã abre em branco, e é assim que o mesmo formulário serve para criar uma conta nova.

A Rota passa a ser /ficha-de-conta/:id.

#Os dois datastores do ecrã

Ainda com o ecrã seleccionado, na categoria Dados:

1. Clica em + registo. Clica no datastore criado para abrir o modal Configurar datastore.
2. Em Nome do datastore, escreve conta.
3. Em API de tabela, escolhe contas.
4. Em Que registo carregar (chave), clica em + campo da chave e monta a condição: campo id, operador eq, valor Param ▸ id.
5. Deixa Carregar automaticamente ligado e fecha em Concluído.

Agora o segundo, para os contactos da conta:

1. Clica em + lista e abre-o.
2. Nome contactosConta, API de tabela contactos.
3. Em Filtros (where), acrescenta: campo conta_id, operador eq, valor Param ▸ id.
4. Ordena por nome ascendente.

#O formulário

1. Arrasta um Painel para a esquerda do canvas. Na categoria Aspecto, liga Mostrar título e escreve Dados da empresa.
2. Arrasta as Caixas de texto para dentro do painel — largar um widget dentro de um painel torna-o filho dele. Para cada uma, na categoria Conteúdo escreve a etiqueta e, na categoria Dados, secção Ligação a dados, escolhe o datastore conta e o campo:

Etiqueta	Campo	Obrigatório
Nome	nome	sim
NIF	nif	não
Sector	sector	não
Cidade	cidade	não
Telefone	telefone	não
Email	email	não

3. Para o estado, usa uma Lista em vez de uma caixa de texto: etiqueta Estado, ligada a conta ▸ estado, Obrigatório ligado, e opções estáticas:

Valor	Etiqueta
ativo	Ativo
prospeto	Prospeto
inativo	Inativo

4. Arrasta uma Tabela para a direita do painel, ligada ao datastore contactosConta, com as colunas nome (Nome), cargo (Cargo) e telefone (Telefone), e o título Contactos desta conta.

#Gravar e voltar

Dois Botões por baixo do painel, com o respectivo evento onClick:

Guardar (ícone save):

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

Voltar (ícone arrow-left):

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

save() valida primeiro — obrigatórios e regras — e só grava se tudo passar; devolve true quando gravou. É por isso que o aviso e a navegação estão dentro do if.

#O ecrã Oportunidades — o quadro kanban

Abre o ecrã Oportunidades.

1. Uma Etiqueta no topo, com o texto Oportunidades.
2. Arrasta um Kanban para baixo dela, a toda a largura.
3. Na categoria Dados, cria o datastore de lista sobre a API oportunidades (sem filtro — o quadro mostra tudo), com Por página a 50.
4. Em Campo de estado (coluna), escolhe fase. É este campo que diz em que coluna cada cartão vive — e é o que é escrito quando alguém arrasta um cartão.
5. Em Fonte das colunas, escolhe Estática e usa + adicionar coluna seis vezes:

Valor	Etiqueta	Cor
prospecao	Prospeção	cinzento
qualificacao	Qualificação	azul
proposta	Proposta	âmbar
negociacao	Negociação	roxo
fechada_ganha	Ganha	verde
fechada_perdida	Perdida	vermelho

6. Liga Permitir arrastar cartões e Contagem de cartões; deixa Coluna para sem categoria desligada.
7. Em Template do cartão, diz o que cada cartão mostra:

Campo	Papel
titulo	Título
conta.nome	Legenda
valor	Valor

8. Por baixo do quadro, acrescenta uma Tabela com o título Todas as oportunidades, ligada a um datastore de lista sobre oportunidades, com as colunas titulo, conta.nome, valor, fase, data_fecho e responsavel.

#Ver o resultado

Não há botão de gravar nos ecrãs: as alterações gravam-se sozinhas, e o canto superior direito diz em que pé estão (A gravar…, Gravado).

Para veres o ecrã a sério, clica em Pré-visualizar: a plataforma grava o que estiver pendente e abre o ecrã na app real, num separador novo do browser. Passas pelo login como qualquer utilizador — as contas que entram na app criam-se na etapa Publicar e usar, e até lá podes usar a que já existir.

#Porque não…?

• Porque não aparece a minha API na lista de datastores? A API está em rascunho. Abre-a e liga Publicada.
• Porque abre sempre uma ficha vazia? O datastore de registo não tem condições em Que registo carregar (chave), ou o parâmetro id não está a chegar na rota. Confirma que a rota é /ficha-de-conta/:id.
• Porque não vejo a coluna conta.nome? O navigator não está incluído nos Campos incluídos da API de tabela — ou o datastore foi configurado antes de o teres marcado. Reabre Configurar datastore e volta a escolher a API para refrescar o retrato dos campos.
• Porque é que o kanban não deixa arrastar? Falta a chave primária no datastore, ou a acção Update na API de tabela.
• Porque é que o gráfico está vazio? O Campo de categoria ou os Campos de valor não estão escolhidos — ou o filtro do datastore não deixa passar nenhuma linha.

Os ecrãs existem, mas ainda não há como saltar entre eles. Próxima etapa: navegação e tema.