Os widgets

Tudo o que se vê num ecrã é um widget. A palette Widgets, à esquerda do canvas, traz 32 widgets de origem — desta página sais a saber para que serve cada um, e com os principais explicados ao detalhe. Se a app tiver widgets programados por ti, aparecem na mesma palette, na secção Custom.

#O catálogo, por categoria

#Campos de formulário

Todos se ligam a um campo de um datastore de registo (secção Ligação a dados) e entram na validação — ver os formulários.

Widget	Para que serve
Caixa de texto	Texto de uma linha. Tem Máscara, modo Password (esconder o texto) e placeholder.
Área de texto	Texto longo, multi-linha — notas, descrições.
Número	Valores numéricos.
Sim/Não	Um interruptor booleano.
Lista	Escolha de opções: Lista fixa, Enum do modelo ou Datastore; com Pesquisável, Multi-selecção e modo Árvore (hierárquica).
Data	Data, Data e hora ou só Hora (o campo Tipo decide).
Cor	Escolha de uma cor.
Ficheiro	Upload por arrasto e/ou botão, com pré-visualização, limite de tamanho e escolha do armazenamento. O limite nunca passa do Ficheiro máximo (MB) das definições da plataforma, até 100 MB. Com No próprio campo (base64), o ficheiro vai dentro do pedido e o limite é de cerca de 3 MB. Cada conta envia até 300 ficheiros e 3 GB por hora (e cada endereço até 20 GB); acima disso, o widget diz que se enviaram ficheiros a mais e pede para tentar mais tarde.

Todos os campos com valor mostram um × discreto à direita que o limpa — numa Lista usada como filtro é a forma de voltar a "todos" sem escolher nada. A Lista simples abre as opções por baixo do campo; com Pesquisável, abre uma caixa de pesquisa e a lista encurta-se ao escrever; com Multi-selecção, cada opção liga e desliga com uma marca.

A Lista mostra 10 opções de cada vez. A propriedade Opções visíveis, em Comportamento, muda esse número (0 mostra todas). Quando há mais opções do que esse número, a lista ganha caixa de pesquisa, mesmo sem Pesquisável, e um rodapé com o total, por exemplo «10 de 245 · escreve para pesquisar». A pesquisa procura em todas as opções e ignora acentos e maiúsculas. Numa Multi-selecção, as opções já escolhidas aparecem primeiro na lista, e o campo mostra as duas primeiras seguidas de «+N».

No rodapé, a lupa (Ver tudo) abre uma janela com todas as opções numa tabela, com pesquisa e 50 linhas por página. Com a Origem das opções em Datastore, as Colunas da janela de escolha acrescentam campos ao lado da etiqueta (por exemplo, o NIF, para distinguir dois clientes com o mesmo nome), e a janela ganha uma barra de filtros sobre esses campos. Numa escolha simples, clicar numa linha escolhe a opção. Numa Multi-selecção, cada linha tem uma marca, Marcar todos marca os resultados de todas as páginas, e só Aplicar grava a escolha; Cancelar não altera nada. A janela tem sempre o mesmo tamanho, com poucos ou muitos resultados.

No KeplinGo, a Lista abre uma folha com a mesma regra: 10 opções, pesquisa e o rodapé com o total. Ver tudo mostra todas as opções na mesma folha, com os campos das Colunas da janela de escolha por baixo de cada etiqueta, e a Multi-selecção só grava com Aplicar.

Com o Carregamento do datastore da Lista em Uma página de cada vez, só a primeira página chega ao ecrã. A pesquisa pergunta então ao servidor, o total do rodapé é o do servidor, a janela de escolha pede cada página ao servidor, e o campo vai lá buscar o nome de um valor gravado que a primeira página não trouxe. Nesse modo, a pesquisa procura na etiqueta (que tem de ser um campo de texto), as maiúsculas e os acentos contam como a base de dados os conta, e Marcar todos não aparece, porque obrigava a trazer todos os registos.

#Acções e navegação

Widget	Para que serve
Botão	A acção clássica. Mostrar: Ícone + Texto, Só ícone ou Só texto; a Acção ao clicar navega, abre um modal ou corre código.
Botão com menu	Um botão que abre mais opções. Aspecto: Dividido (o corpo age, a seta abre o menu), Menu ou Hamburguer. Cada opção pode esconder-se ou desactivar-se por condições.
Link	Texto clicável — Destino: Ecrã da app (com parâmetros) ou URL externo (com Abrir em nova aba).
Breadcrumb	O caminho "estás aqui", com níveis clicáveis e o último nível fixo ou ligado a um campo.
Exportar	Um botão que descarrega os dados de um datastore em folha de cálculo (.xlsx) — campos escolhidos, Linha de cabeçalho opcional e Nome do ficheiro com {date}.

O Exportar lê os dados no momento do clique, por blocos, até 50 000 linhas; acima disso, o ficheiro sai com as primeiras 50 000 e aparece um aviso. O evento onExport diz se o ficheiro foi cortado (truncated).

No KeplinGo o ficheiro sai em CSV; um texto que o Excel leria como fórmula (começado por = ou @, por exemplo) leva um apóstrofo à frente.

#Estrutura

Widget	Para que serve
Painel	Um contentor com moldura e título — arruma widgets que passam a mover-se em conjunto.
Abas	Um contentor com separadores; cada widget filho pertence a uma aba. Estilo das abas: Caixa, Pílulas ou Sublinhado.
Barra fixa	Uma barra a toda a largura, pinada ao Topo ou ao Rodapé do ecrã — para barras de acções sempre visíveis.
Linha	Uma linha separadora, Horizontal ou Vertical — a cor e o traço vêm do Aspecto.

#Conteúdo e media

Widget	Para que serve
Etiqueta	Texto simples — títulos, legendas, valores soltos. Aceita Valores da frase ({n} no texto).
Markdown	Texto rico escrito em Markdown — fixo ou vindo de um campo.
Imagem	Uma imagem por URL fixo, Asset da app ou Campo (dinâmico); Ajuste: Conter, Preencher ou Esticar.
Página externa	Embebe uma página de fora (um mapa, um vídeo, BI de terceiros) ou HTML escrito por ti. Corre isolado: não vê a sessão nem os dados da app.

#Dados

Widget	Para que serve
Tabela	A grelha de registos — colunas tipadas, ordenação, selecção e botões de acção. Detalhe abaixo.
Lista	Registos em lista vertical, com campos em papéis (Título, Subtítulo, Corpo, Legenda) e imagem opcional.
Cartões	O mesmo template da Lista, mas em grelha de cartões com N Colunas.
Gráfico	Séries desenhadas — barras, linhas, tartes e mais. Detalhe abaixo.
KPI	Uma faixa de indicadores numéricos com tendências, alvo e sparkline. Detalhe abaixo.
Barra de filtros	Condições em crachás (campo, operador, valor) que filtram uma Tabela, Lista, Cartões, Kanban ou Gráfico do ecrã. Detalhe abaixo.

#Quadros e planeamento

Widget	Para que serve
Kanban	Cartões arrastáveis entre colunas de estado. Detalhe abaixo.
Calendário	Eventos em vistas Dia/Semana/Mês/Ano. Detalhe abaixo.
Gantt	Barras de início→fim com progresso, grupos e dependências. Detalhe abaixo.

#Documentos e processos

Widget	Para que serve
Relatório	Mostra um relatório da app (PDF) dentro do ecrã, com parâmetros ligados ao que está no ecrã e Barra de acções para actualizar e descarregar.
Estado do processo	O historial e o passo actual dos workflows de um registo, com botões de decisão quando a tarefa aberta é de quem está a ver.
As minhas tarefas	A caixa de entrada de tarefas de workflow do utilizador com sessão — abre o ecrã da tarefa e decide dali.

#A Tabela

A Tabela é o widget mais usado da plataforma: liga-se a um datastore de lista e mostra os registos em grelha, com paginação, ordenação e selecção.

O rodapé com o total e as setas de página só aparece quando os registos não cabem numa página. O mesmo vale para os widgets Lista e Cartões.

As datas que vêm da API mostram-se na língua da app, e uma coluna só de dia mostra só o dia.

#Colunas

Ao ligares o datastore, as colunas nascem uma por campo. Depois afinas: em Colunas, usa + coluna para acrescentar, e clica numa coluna no canvas para a editar — o inspector muda para ela.

Cada coluna tem Cabeçalho, Largura, Ordenável pelo cabeçalho, Oculta — e um Tipo:

Tipo	O que faz
Texto	O valor tal como está, com Máscara opcional (# = carácter).
Número	Formata o valor: Número (regional) (com Casas decimais, Separador de milhares, Compacto — 1,2 M em vez de 1 234 567 —, Prefixo e Sufixo) ou Máscara (# = dígito).
Ligação	A célula fica clicável. Destino: Ecrã da app (com parâmetros vindos de Campo da linha, Parâmetro do URL ou Valor fixo) ou Script — código teu a correr no clique. É a coluna certa para abrir a ficha de um registo a partir da lista: a coluna que identifica a linha (nome, descrição, data) leva ao ecrã da ficha com o id da linha; um ecrã em modo modal ou painel lateral abre por cima e, ao fechar, a lista recarrega.
Imagem	Mostra a imagem cujo endereço/conteúdo está no campo.
Ficheiro	Um link de download para o ficheiro referido no campo.
Gráfico spark	Um gráfico pequeno por linha, em Linhas ou Barras, sem eixos nem rótulos. A série vem de um Campo com lista (uma lista de números em JSON ou da API, ou um texto como 3,5,4) ou de Vários campos da linha, um ponto por campo. Podes escolher a Cor, Mostrar último valor ao lado, e uma Escala fixa (mínimo e máximo) para comparar linhas entre si. Esta coluna não ordena pelo cabeçalho.

Uma coluna de um campo de relação (cliente.nome) não ordena pelo cabeçalho: a ordenação corre no servidor, que só conhece os campos da própria tabela.

#Acções da tabela

Na categoria Comportamento, a secção de acções cria os botões CRUD: Refrescar, Adicionar novo, Editar registo, Remover registo e Remover múltiplos. Cada acção ligada cria um botão solto no canvas, ligado à tabela — posicionas e estilizas esse botão como qualquer outro.

• Adicionar novo e Editar registo abrem um ecrã ou um modal à tua escolha (tipicamente o formulário do registo), com os parâmetros preenchidos a partir da linha.
• Editar registo e Remover registo só ficam activos com uma linha seleccionada; Remover múltiplos trabalha sobre a Selecção múltipla (o interruptor que acrescenta a coluna de checkboxes).
• As acções que escrevem exigem que o datastore tenha chave primária — o inspector avisa: O datastore precisa de uma chave primária.

#Formulários (inputs + registo + validação)

Não há um widget "formulário": um formulário é a soma de três peças, e é essa liberdade que te deixa desenhar a ficha como quiseres.

1. Cria um datastore de registo no ecrã (ver Datastores e dados) — por exemplo, conta, carregado pela chave vinda do parâmetro id da rota.
2. Arrasta os campos de formulário (Caixa de texto, Lista, Data…) e, em cada um, liga a Ligação a dados ao campo certo do datastore.
3. Põe um Botão "Gravar" cujo evento grava o datastore — a acção pré-definida Gravar datastore do editor de eventos escreve o código por ti (ver Eventos e o SDK).

A validação vive em cada campo, na categoria Validação:

• Obrigatório — o campo tem de vir preenchido.
• As regras standard: Mín. caracteres, Máx. caracteres, É email, É telefone, É número, Valor mín., Valor máx., Padrão (regex) e Igual ao campo (confirmação de password, por exemplo).
• Validação com script — para lógica tua: o código recebe value (o valor actual do campo) e devolve true se válido, ou a mensagem de erro. Um NIF, um IBAN, uma regra de negócio.

Ao gravar, a validação corre toda: obrigatórios primeiro, depois as regras, depois o script. O registo só segue se tudo passar.

Um campo com erro fica com a borda vermelha, e a mensagem aparece por baixo dele, no espaço entre widgets. O campo e o rótulo não mudam de sítio. Para a mensagem se ver inteira, deixa pelo menos 16 píxeis entre um campo e o widget de baixo, e entre um campo e o fundo do painel ou separador que o contém.

#O Gráfico

O Gráfico liga-se a um datastore e desenha séries. Em Tipo de gráfico escolhes: Barras, Linha, Área, Tarte / Donut, Dispersão, Radar, Gauge (medidor), Funil ou Mapa de calor.

O essencial é o mapeamento, na categoria Dados:

• Campo de categoria (eixo X / fatias) — o que separa as barras/fatias.
• Campos de valor — um ou mais campos numéricos; cada um é uma série.
• Campo de série (agrupamento) — em alternativa aos vários valores: pivota pelo primeiro campo de valor e cria uma série por valor distinto (sem valores, conta registos).

E depois o acabamento:

Opção	O que faz
Empilhado, Horizontal, Linhas suaves, Valores nos pontos	Variações do desenho, conforme o tipo.
Legenda, Posição da legenda, Tooltip	O chrome do gráfico. A legenda também se arrasta directamente no gráfico para a posicionar.
Formato dos valores	O mesmo formato das colunas Número da tabela, aplicado a eixos, etiquetas e tooltip.
Escala dos valores	Linear ou Logarítmica — a logarítmica serve quando as séries têm ordens de grandeza diferentes.
Usar um segundo eixo	Um eixo à direita com escala própria — para juntar um total em euros e uma contagem no mesmo gráfico.
Séries	Tipo por série (combos de barras com linhas) e que séries vão para o 2.º eixo.
Opções avançadas	Um editor de código com todas as propriedades do motor de gráficos, com autocomplete — aplicadas por cima da configuração, para os casos que os campos não cobrem.

#O KPI

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

Cada indicador (em Indicadores ▸ Acrescentar indicador) tem:

• Rótulo e ícone, com Posição da legenda (Acima do valor / Abaixo do valor).
• Valor (campo) + Agregação (Soma, Média, Contagem, Máximo, Mínimo, Primeiro, Último) sobre o conjunto de dados — ou um Valor manual quando não há dados ligados.
• Tendências (Acrescentar tendência) — comparações por baixo do número, com Campo de referência, formato Percentagem ou Valor absoluto, e Menos é melhor (inverte as cores): numa dívida a crescer, a seta tem de ser vermelha.
• Alvo — Sem alvo, Valor manual ou Campo do datasource, com Barra de progresso opcional.
• Mostrar sparkline — a mini-linha do histórico, com Campo da série.
• Período (do campo) — de que fecho fala o número (uma data ISO mostra-se como MM/AAAA).

O conjunto de dados é partilhado pelo widget, mas cada indicador pode ter um Conjunto de dados próprio.

#O Kanban

O Kanban mostra os registos como cartões em colunas — o pipeline de oportunidades da Gestão de Clientes é um kanban por estado.

1. Liga o datastore e escolhe o Campo de estado (coluna) — o campo que diz em que coluna está cada cartão.
2. Define a Fonte das colunas: Estática (adicionas cada coluna com Etiqueta, Valor e cor) ou Enum (as colunas vêm dos valores de um enum do modelo).
3. Compõe o Template do cartão — os campos e papéis, como na Lista.

Com Permitir arrastar cartões ligado, mover um cartão grava logo o novo estado no registo. Campo de ordem (um campo numérico) torna a ordenação dentro da coluna persistente. Coluna para sem categoria apanha os registos cujo estado não bate com coluna nenhuma; Contagem de cartões mostra o total no cabeçalho.

As acções: Clique num cartão (editar) e Criar cartão (botão na coluna) — cada uma pode navegar para um ecrã, abrir um modal (com os parâmetros da linha e da coluna) ou emitir um evento para código teu.

#O Calendário

O Calendário mostra registos com data como eventos, nas vistas Dia, Semana, Mês e Ano.

• Campos: Campo de data (início), Campo de fim (opcional) (eventos multi-dia), Campo de título.
• Cor dos eventos: Única ou Por campo — com um mapa valor → cor (um enum de tipo, por exemplo).
• Vista: Vista inicial, Vistas disponíveis, 1º dia da semana (Segunda/Domingo), Máx. eventos por dia na vista mês, horas de Início/Fim nas vistas de dia/semana, Barra de navegação e Botões de mudança de vista.
• Acções: Clique num evento (editar) e Selecção de dia/intervalo (criar) — o início/fim seguem para o ecrã de destino como parâmetros, prontos a pré-preencher o formulário de criação.

O calendário só carrega os registos do intervalo visível — mudar de mês vai buscar o mês novo, não a tabela inteira.

#O Gantt

O Gantt desenha barras de início→fim numa linha temporal — planeamento de projectos, campanhas, onboarding de clientes.

• Campos: Campo de início, Campo de fim, Campo do rótulo, Campo de progresso (0–100) e Campo de grupo (agrupa linhas).
• Campo de dependências — os IDs (chave primária) dos predecessores, em lista JSON ou separados por vírgula; o Gantt desenha as setas.
• Zoom inicial (Dia, Semana, Mês), Linha de hoje e Sombrear fins de semana.
• Acções: Clique numa barra (editar) e Clique em espaço vazio (criar) — a data clicada segue como parâmetro.

O Gantt é de leitura: as barras não se arrastam — as datas mudam-se no formulário do registo.

#A Barra de filtros

A Barra de filtros deixa quem usa a app filtrar uma lista por qualquer campo, sem que tenhas de desenhar um campo de filtro por cada coluna. Fica por cima de uma Tabela, Lista, Cartões, Kanban ou Gráfico e escreve as condições em crachás.

1. Arrasta a Barra de filtros para o ecrã e, em Dados, escolhe o Widget alvo — o widget de listagem cujo datastore recebe as condições.
2. Em Campos filtráveis, escolhe os campos a oferecer. Sem escolha, a barra oferece todos os campos simples do datastore do alvo; os cabeçalhos das colunas da tabela servem de rótulo. Os campos de relação (cliente.nome) não se oferecem: o filtro corre no servidor, que só conhece os campos da própria tabela.
3. Opcional: em Valores visíveis, escolhe quantos valores sugeridos a lista mostra de cada vez (10 por omissão; 0 mostra todos). A pesquisa procura sempre em todos os valores, e um rodapé diz quantos existem. No passo do valor, a lupa do rodapé abre a janela de escolha com todos os valores do campo.

Na app, cada condição escreve-se em três passos, sempre à vista: o campo, o operador e o valor. As opções do passo seguinte aparecem sozinhas; escrever filtra-as. Os valores sugeridos saem dos dados carregados, mas o que se escreve vale sempre, mesmo que não esteja na lista.

Os operadores dependem do tipo do campo: texto (contém, igual a, começa por…), número e data (comparações), e listas (igual a, diferente de). Qualquer de e nenhum de aceitam vários valores no mesmo crachá: cada escolha entra, e Enter ou Aplicar fecha a condição. O × de um crachá tira essa condição; o × da barra limpa tudo.

Quando uma condição fecha, a lista não volta a abrir sozinha: a barra fica pronta a escrever. Para mais um filtro, escreve, clica na barra ou carrega em ↓.

As condições juntam-se às do datastore do alvo (Filtros (where)) e o pedido vai ao servidor com paginação — filtrar não traz a tabela inteira. Os filtros por widget (uma Lista ligada a uma condição do datastore) continuam a existir e podem viver no mesmo ecrã: a dropdown rápida para o filtro mais usado, a barra para todo o resto.

Nos campos de data, o valor escreve-se como se lê: «26/09/2026», «26-09-2026», «26.09.2026» ou «2026-09-26», com ou sem hora. Quando o dia e o mês se podem confundir, o dia vem primeiro. Uma data sem hora vale pelo dia inteiro: menor ou igual a 26/09/2026 inclui os registos desse dia, e maior que 26/09/2026 começa no dia seguinte. Diferente de e nenhum de incluem os registos com o campo vazio.

#Porque não…?

• Porque não aparece a secção Validação no meu widget? Só os campos de formulário validam — um Botão ou uma Etiqueta não têm valor para validar.
• Porque é que o widget aparece na palette mas cinzento no canvas? Está desactivado (interruptor Activo na categoria Layout) ou uma regra/evento desactivou-o.
• Porque não vejo dados no canvas? O canvas mostra amostras — os dados reais aparecem na pré-visualização e na app publicada. Confirma a ligação no capítulo Datastores e dados.
• Porque é que a Barra de filtros diz "Sem widget alvo"? Falta escolher o Widget alvo em Dados — só os widgets com datastore de lista (Tabela, Lista, Cartões, Kanban, Gráfico) servem de alvo.