Parâmetros de ecrã

Um parâmetro é um valor que o ecrã recebe de fora e que os seus widgets podem usar nas consultas. É o mecanismo que faz um ecrã de detalhe mostrar aquele produto e não outro.

Declarar

Nas propriedades do ecrã, a secção Parâmetros aceita quantos forem precisos. Cada um tem:

• um nome, que começa por letra e usa letras, dígitos e _;
• a marca de obrigatório.

O nome é o que se usa depois nas condições e no código. Escolha nomes claros: produto, lojaId, mes.

Usar numa consulta

A condição compara um campo com o parâmetro:

Produtos.produto  eq  {parâmetro: produto}

Esta origem ainda não tem seletor na secção Condições do construtor visual: escreve-se pelo editor de código do ecrã, ou pede-se a um assistente ligado por MCP. Ver Filtros da consulta.

Todos os widgets do ecrã podem usar o mesmo parâmetro. É assim que um ecrã de detalhe com quatro widgets mostra os quatro a falar do mesmo produto.

Usar no código

Os parâmetros do ecrã actual estão disponíveis nos eventos:

const produto = keplin.nav.params.produto;
keplin.ui.toast(`A mostrar ${produto}`);

De onde vêm os valores

Situação	Origem
Detalhe aberto por clique	O campo da linha clicada
Detalhe aberto por link	O que estiver configurado no link
Detalhe aberto por código	O objecto passado a openModal
Ecrã normal alcançado por navegação	Os segmentos da rota

Encadear detalhes

Quando um detalhe abre outro, o parâmetro do ecrã actual pode ser passado ao seguinte — origem parâmetro em vez de campo.

É o que permite abrir o detalhe de uma loja a partir do detalhe de uma região, mantendo a região como contexto:

Ecrã "Detalhe da região"   params: regiao
  └─ tabela de lojas, ao clique abre:
     Ecrã "Detalhe da loja"  params: regiao (do parâmetro), loja (do campo)

Parâmetros obrigatórios

Um parâmetro obrigatório assinala que o ecrã não faz sentido sem ele. Serve sobretudo de documentação para quem configura o widget que o abre — e evita ligar um detalhe esquecendo metade das chaves.

O evento de mudança

Um ecrã tem três eventos próprios: onLoad, onParamsChange e onUnload.

onParamsChange corre quando os parâmetros mudam sem o ecrã ser recriado — útil para ajustar títulos ou recarregar conjuntos que não dependem directamente de uma condição.

Ver Eventos e código.

Erros frequentes

O ecrã abre mas mostra tudo. A consulta não tem condição ligada ao parâmetro. Sem condição, o parâmetro chega mas não é usado.

O ecrã abre vazio. O valor chega mas não casa com nenhum registo. Costuma ser diferença de nome: o campo passado é o nome de saída de uma consulta e o campo comparado é outro.

O parâmetro chega vazio. O widget que abre o detalhe indica um campo que o seu conjunto de dados não devolve.