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.

#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}.

#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.

#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.

#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.
Imagem	Mostra a imagem cujo endereço/conteúdo está no campo.
Ficheiro	Um link de download para o ficheiro referido no campo.

#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.

#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.

#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.