Eventos e código

A maior parte do que um dashboard faz configura-se sem escrever nada. Para o resto há eventos: código TypeScript que corre no navegador quando algo acontece.

Quando precisa disto

Praticamente nunca, para o que é comum. Antes de escrever código, confirme que não há caminho configurado:

Quer fazer	Sem código
Filtrar vários widgets	Filtros do dashboard
Filtrar um widget ao clicar noutro	Cruzamento
Abrir um detalhe ao clicar numa linha	Drill
Navegar para outro ecrã	Widget de Link
Calcular um rácio	Medidas calculadas

O código é para o que sobra: mostrar e esconder widgets conforme uma escolha, validar uma combinação, escrever uma mensagem, guardar uma preferência local.

Onde se escreve

Cada widget declara os eventos que pode emitir — a lista completa está em Catálogo de widgets. Com o widget seleccionado, a secção Eventos do inspector abre um editor de código para cada um.

O ecrã tem três eventos próprios:

Evento	Quando corre
onLoad	Ao montar o ecrã
onParamsChange	Quando os parâmetros mudam sem o ecrã ser recriado
onUnload	Ao sair do ecrã

O editor

O editor é o Monaco — o mesmo do Visual Studio Code — com autocomplete que conhece:

• todo o SDK keplin;
• os identificadores dos widgets deste ecrã, como valores possíveis;
• os nomes dos conjuntos de dados deste ecrã.

Escrever um identificador que não existe é assinalado no momento, não descoberto mais tarde.

Escreve-se TypeScript; o que corre é o JavaScript equivalente.

Código mal formatado é recusado ao gravar

A gravação valida o código e recusa o que não estiver formatado, com a mensagem exacta. É deliberado: a resposta chega imediatamente a quem escreveu, em vez de ficar um aviso que ninguém lê.

O essencial do SDK

Tudo vive dentro do objecto keplin. A referência completa está em SDK de eventos.

// O que veio no evento
const linha = keplin.event.row;

// Widgets
keplin.widgets.get("w_detalhe").hide();
keplin.widgets.get("w_botao").setEnabled(false);

// Conjuntos de dados
const store = keplin.data.store("vendasMensais");
store.reload();
const linhas = store.rows();

// Interface
keplin.ui.toast("Sem dados para este período", "info");
const ok = await keplin.ui.confirm("Limpar os filtros?");
keplin.ui.clearDrilldown();

// Ecrãs
await keplin.ui.openModal("scr_detalhe", { produto: "Café Nortada Clássico 1kg" });
keplin.ui.closeModal({ confirmado: true });

// Navegação e parâmetros
keplin.nav.go("/vendas-visao-geral");
const produto = keplin.nav.params.produto;

// Sessão
if (keplin.session.hasRole("Analista")) { /* ... */ }

// Armazenamento local
keplin.storage.set("ultimaRegiao", "Norte");

Exemplos que valem a pena

Esconder um widget quando não há dados

// onDataLoaded de uma tabela
const vazio = keplin.data.store("topProdutos").rows().length === 0;
keplin.widgets.get("w_produtos").setProps({ visible: !vazio });
keplin.widgets.get("w_semDados").setProps({ visible: vazio });

Avisar quando um filtro não devolve nada

// onDataLoaded
if (keplin.data.store("vendasMensais").rows().length === 0) {
  keplin.ui.toast("Nenhuma venda no período escolhido", "info");
}

Guardar a última escolha

// onChange de uma lista pendente
keplin.storage.set("regiao", String(keplin.event.value ?? ""));

// onLoad do ecrã
const guardada = keplin.storage.get<string>("regiao");
if (guardada) keplin.widgets.get("w_regiao").setValue(guardada);

Confirmar antes de uma acção

// onClick de um botão
if (await keplin.ui.confirm("Limpar todas as selecções?")) {
  keplin.ui.clearDrilldown();
}

O que o código não pode fazer

O DeepVisuals é um produto de visualização. O SDK não tem escrita:

• não há mutações de dados;
• não há criação nem alteração de utilizadores;
• as consultas que o código faz passam pelo mesmo caminho restrito dos widgets, limitado às entidades que este ecrã usa.

O navegador não conhece o endereço dos dados nem transporta credenciais de acesso a eles.

Dashboards públicos

Num dashboard aberto por link público não há sessão: keplin.session.user é null e hasRole devolve sempre falso. Código que dependa do utilizador tem de tratar esse caso.

Um conselho

Código num dashboard envelhece pior do que configuração: não aparece no inspector, não é óbvio para quem abre o ficheiro no ano seguinte, e um identificador renomeado parte-o em silêncio.

Se escrever, escreva pouco e comente porquê.