Editor e widget dos Portais

O Editor dos Portais combina um repositório de arquivos navegável com um compositor visual. Ambos os modos operam sobre o mesmo rascunho: as alterações visuais atualizam os fontes e as partes gerenciadas diretamente no código são preservadas.

Ao iniciar, o Editor abre a primeira página disponível no modo Visual. Se o Portal não tiver páginas, abre portal.json no modo Código.

A interface do Editor acompanha imediatamente o tema claro ou escuro escolhido no Sybot. Barra de ferramentas, painéis, Inspector e diálogos mudam de paleta sem recarregar a página; o canvas e os widgets do Portal mantêm o tema e os estilos definidos para o conteúdo publicado.

Os seletores Código e Visual ficam entre o nome do Portal e o estado de salvaguarda. Guia de widgets precede Exportar na barra de ações. Em viewports estreitos, a linha permanece única: as etiquetas desaparecem progressivamente da direita para a esquerda, deixando os ícones com tooltips e nomes acessíveis. A ajuda para arrastar e redimensionar continua visível na barra da Canvas sem o resumo anterior dos atalhos de teclado.

No lado esquerdo, a barra de atividades abre alternadamente Adicionar Widget, Páginas, Imagens, Explorer, Diagnóstico e Problemas e Propriedades do Portal. O ícone das propriedades fica na parte inferior da barra. Apenas um painel fica visível de cada vez; selecionar novamente o ícone ativo fecha-o. No modo Visual, o Inspector permanece fixo à direita. Durante a sessão, o Editor memoriza o painel aberto e a largura escolhida para a coluna esquerda.

Adicionar Widget mostra inicialmente as categorias com a quantidade de elementos e um chevron. Selecione uma categoria para expandir os respetivos cartões; Business Intelligence contém separadamente Relatório Power BI e Dashboard Qlik. Pesquisar widget filtra nomes, categorias e chaves técnicas em tempo real e abre automaticamente os grupos com resultados.

O painel Páginas mantém Adicionar página no topo e lista abaixo todas as páginas do Portal. A página ativa fica destacada; nomes longos são truncados sem quebrar o layout e o nome completo permanece disponível ao passar o cursor. Selecionar uma página abre-a diretamente na Canvas. Alternar para Widgets, Explorer ou Problemas não altera a página atual. Adicionar página solicita um nome, cria e salva de forma assíncrona o documento inicial em pages/ e abre-o na Canvas.

O painel Imagens reúne a ligação ao catálogo partilhado, o carregamento a partir do computador e as imagens já presentes no Portal. Cada imagem mostra uma pré-visualização e o nome do ficheiro e pode ser eliminada após confirmação; a grelha é atualizada sem recarregar o Editor.

Na Canvas, cada widget é representado por um cartão compacto que mostra o ícone, nome, tipo, tamanho na grelha e visibilidade em computador, tablet e smartphone. O cartão preserva as cores, o fundo e a tipografia configurados, enquanto textos longos são abreviados sem cobrir os controlos de arrastar e redimensionar. Use Pré-visualização para testar o conteúdo e o comportamento completos do widget.

Duplicar widget cria uma instância independente na mesma página ou noutra página. Para um widget personalizado, também copia todos os ficheiros do componente e as alterações às fontes ainda não guardadas, com uma nova chave de componente. A configuração, as ligações, o estilo e as associações externas são preservados; editar ou eliminar a cópia não afeta o original. A cópia permanece local, mantém o modo sandboxed/trusted e não herda a ligação à versão assinada do catálogo; a partilha exige guardar explicitamente no catálogo. O componente e a página são guardados em conjunto: se ocorrer um erro, a duplicação é anulada. As instâncias existentes que partilham um componente continuam a partilhá-lo.

Cada cópia local pode ser guardada no catálogo como um pacote distinto a partir de v1, em qualquer ordem. O botão desaparece apenas para o componente já associado; continua disponível para cópias não associadas. Se os nomes coincidirem, o servidor acrescenta um sufixo e atualiza o nome e o manifesto no editor, preservando os ficheiros auxiliares. O catálogo de widgets personalizados mostra apenas pacotes guardados explicitamente no catálogo. Os componentes locais e as cópias ainda não guardadas nunca geram cartões no catálogo; continuam disponíveis no Canvas e no Explorer.

Para eliminar um widget, selecionar Eliminar widget no Inspector, ou premir Delete ou Backspace fora de um campo. Após confirmação, apenas a instância selecionada é removida dessa página. Enquanto outras instâncias referenciarem o componente, incluindo noutras páginas, as fontes e a associação ao catálogo permanecem inalteradas. Eliminar a última instância de um componente guardado no catálogo remove as fontes locais e desliga o pacote de forma atómica: o widget permanece entre os Objetos não utilizados, pronto para ser novamente inserido. A ação explícita do Explorer elimina todo o componente e todas as referências nas páginas.

Modo Código

O modo Código mostra:

• Explorer, para procurar, criar, renomear e organizar arquivos;
• Carregar imagem, para adicionar ao repositório ativos PNG, JPEG, GIF ou WebP;
• abas para arquivos abertos;
• editor com destaque para JSON, HTML, CSS e JavaScript;
• estado de salvamento e número da revisão atual;
• painel Problemas com erros e indicações corrigíveis.

No Explorer, o chevron junto de cada diretório permite expandir ou recolher apenas esse ramo. O estado dos diretórios é mantido durante a sessão de edição, enquanto uma pesquisa expande temporariamente os ramos necessários para mostrar as correspondências.

As alterações são salvas de forma assíncrona. Se o rascunho foi atualizado por outra sessão, o editor interrompe a salvaguarda e sinaliza o conflito: recarregue a versão atual antes de retomar o trabalho.

Ao fechar ou sair do Editor, a sessão de edição é liberada imediatamente. Outro usuário pode então editar o mesmo Portal sem aguardar a expiração automática da sessão anterior.

Use Checkpoint para fixar uma revisão imutável e reconhecível do rascunho. Um checkpoint não publica o Portal.

Abrindo um arquivo que não representa uma página — por exemplo portal.json, um Data Resource, um CSS ou um arquivo de componente — o editor passa automaticamente para Código. O compositor Visual permanece associado apenas às páginas e nunca mostra o canvas de um arquivo aberto anteriormente. O modo escolhido para cada página é memorizado durante a sessão de edição: se uma página estava aberta em modo Visual, regressa automaticamente a Visual depois de consultar um arquivo de configuração.

Para criar uma página, selecione Novo arquivo e use um caminho JSON sob pages/, por exemplo pages/dashboard.json ou pages/orders/detail.json. O nome do arquivo é livre: o editor gera automaticamente UUID, título, layout de grade e lista de widgets. O Editor adiciona automaticamente a rota em portal.json e a entrada de navegação em shell.json. Ao eliminar a página, ambas as associações são removidas sem recarregar a interface.

Modo Visual

O modo Visual disponibiliza paletas, canvas e Inspector. Ao selecionar um widget, Propriedades abre sempre e a configuração é organizada em três abas:

• Propriedades contém título, dados, fontes, bindings e opções funcionais;
• Estilo contém controles visuais, Style JSON e CSS scoped;
• Avançado contém posição, largura, altura e Propriedades JSON.

Mudar de aba não desmarca o widget nem perde os valores atuais, inclusive durante o salvamento assíncrono. As mesmas abas estão disponíveis para widgets padrão e personalizados, Visões de Usuário, BPMN, Power BI e Qlik. Também é possível navegar com as setas esquerda/direita, Home e End.

As propriedades guiadas são aplicadas e salvas quando o controle muda; um toaster confirma o resultado. Salvar alterações avançadas serve, em vez disso, para quadros JSON e CSS, nos quais é normal ter conteúdo temporariamente inválido durante a digitação. O estado no cabeçalho distingue alterações em andamento, salvamento e fonte salva.

Os campos do Inspector dependem do widget: rotas, imagens, Visões de Usuário, widgets individuais de uma Visão, Workflow, parâmetros e Data Resource são escolhidos de menus filtrados no Projeto. Os seletores de rota mostram apenas as páginas da navegação ativa do Portal e atualizam-se sem abrir manualmente os ficheiros fonte. As cores podem ser escolhidas com o picker ou inseridas como valor CSS ou design token.

Os presets Viewport declaram o tamanho simulado. A barra de zoom oferece −, +, reposição para 100% e Ajustar. Ajustar utiliza tanto a largura como a altura disponíveis, reduz uniformemente o canvas e mantém as proporções da Preview. Um clique na percentagem repõe 100%; um duplo clique permite introduzir um valor de 5% a 200%. Com zoom personalizado, as barras de deslocamento permitem explorar as áreas que ficam fora do espaço de trabalho. O zoom altera apenas a visualização no editor, não a geometria guardada nem a renderização em execução. Cada widget também mostra largura × altura em células da grelha.

Para modificar a geometria de um widget:

• arrastar a alça no canto superior esquerdo para movê-lo;
• arrastar a alça no canto inferior direito para redimensioná-lo;
• usar Alt + seta para movê-lo de uma célula;
• usar Shift + Alt + seta para modificar sua largura ou altura de uma célula.

Para excluir um widget, selecione-o e use Excluir widget no Inspector. Alternativamente, pressione Delete ou Backspace quando o cursor não estiver em um campo. O editor sempre pede confirmação.

Quando uma região contém propriedades não gerenciadas pelo compositor, o editor a identifica como gerenciada pelo código e a preserva durante atualizações visuais.

Para configurar a página em vez de um widget, clique em uma área livre do fundo do canvas. O Inspector Estilo da página permite definir cor, fundo, espaçamento interno e altura mínima; Estilo JSON e CSS scoped da página permanecem disponíveis para ajustes avançados.

Propriedades do Portal abre na coluna esquerda e deixa o Inspector direito disponível para o widget selecionado. A aba Geral contém o nome, o código trusted e os controlos Mostrar Header e Mostrar Navegação. Estes dois controlos da Shell são guardados imediatamente e a Pré-visualização reflete o título e a barra de navegação. Para Owners, Acesso contém colaboradores, permissões e audiência runtime. A mudança de aba preserva valores ainda não salvos; carregamento, salvamento e diagnósticos continuam assíncronos sem recarregar o Editor.

Configurar aparência e CSS

O Estilo guiado expõe cor, fundo, tamanho do texto, alinhamento, espaçamento e raio da borda. Os valores aceitam sintaxe CSS normal, por exemplo #0f172a, 1rem ou 8px.

A Configuração avançada permite utilizar propriedades CSS em kebab-case, estados e breakpoints:

{
  "color": "#0f172a",
  "background-color": "#ffffff",
  "padding": "1rem",
  "states": {
    "hover": {"background-color": "#e0f2fe"}
  },
  "breakpoints": {
    "md": {"font-size": "18px"}
  }
}

O campo CSS scoped permite intervir em qualquer detalhe sem influenciar os outros widgets. & representa o container da instância; .portal-text seleciona o conteúdo do widget de Texto:

&:hover { transform: translateY(-2px); }
.portal-text { font-weight: 600; letter-spacing: .02em; }

Selecione Salvar alterações avançadas para registrar JSON e CSS na página. A Preview mostra a renderização compilada definitiva.

Catálogos do Projeto

Os botões Widgets personalizados e Imagens abrem um catálogo unificado. Cada elemento sempre indica a origem: Portal atual, outro Portal do mesmo Projeto, Visão de Usuário publicada ou catálogo compartilhado das Visões. Objetos externos ao Projeto ou inacessíveis ao usuário não são exibidos.

Em Widgets personalizados, o seletor junto à pesquisa alterna entre as vistas Cards e Tabela. A tabela oferece ordenação, seleção múltipla e páginas de dez registros. O menu de cada widget permite inserir a versão escolhida, exportar o JSON, abrir uma pré-visualização estática segura ou eliminá-lo; a confirmação lista os Portais que o utilizam. Importar widget carrega um JSON exportado de outro Projeto. Cada salvamento cria uma nova versão incremental sem substituir versões existentes.

A paleta inclui também os widgets das Visões de Usuário publicadas do Projeto. É possível incorporar tanto widgets padrão — incluindo gráficos, KPI, tabelas e mapas — quanto widgets do catálogo personalizado. A seleção registra Visão, versão publicada e chave do widget; uma release permanece, portanto, estável mesmo que a Visão seja modificada posteriormente.

Quando se usa uma imagem ou um componente proveniente de outro objeto, o editor cria uma cópia no repositório do Portal. Essa materialização torna os checkpoints, builds e releases reprodutíveis; a card do catálogo conserva a indicação da origem para evitar ambiguidades.

Widgets disponíveis

O catálogo gerenciado inclui:

• Texto, Hero, Card, Imagem e Divisor;
• Link, Menu, Páginas de navegação e Breadcrumb;
• Seção, Painel expansível, Sidebar e Drawer;
• Formulário somente leitura, Formulário de dados, Tabela de dados, Gráfico de barras e Exportação de dados;
• Visão de Usuário completa e widget único de Visão de Usuário;
• Ação de Workflow;
• Relatório Power BI e Dashboard Qlik;
• Widget personalizado sandbox.

Cada widget suporta propriedades de estilo, estados visuais e breakpoints. O CSS scoped permite personalizar também hover, focus, estado ativo e estado desabilitado sem modificar os outros componentes da página.

O botão Guia do widget abre a referência integrada do widget selecionado: lista propriedades, tipos, valores padrão, capacidades e exemplos de estilo. A referência completa também está disponível em Reference dei widget.

Carregar e usar uma imagem

1. Se o arquivo é local, use Carregar imagem no Explorer e escolha um PNG, JPEG, GIF ou WebP.
2. Para reutilizar um ativo, abra Imagens e filtre o catálogo por nome ou origem.
3. Selecione Usar imagem ou Copiar e usar: o editor propõe um caminho sob assets/ e preenche o widget selecionado.
4. Preencha sempre alt, em seguida escolha o ajuste (contain, cover, fill, none, scale-down) e a posição.
5. Verifique o resultado na Preview.

A altura definida para o widget na grade determina também o espaço ocupado pela imagem. Por padrão, a imagem é contida sem distorções; o CSS scoped pode modificar object-fit através do seletor .portal-image.

Data Manager e consultas visuais

Dados abre o Data Manager do Portal. Não é necessário conhecer antecipadamente a estrutura da pasta data/:

1. Criar um Data Resource e atribuir chave e nome;
2. escolher Conexão Environment ou Modelo Semântico;
3. para Environment carregar o catálogo, em seguida escolher esquema, tabela, dimensões, medidas, agregações e alias;
4. para um Modelo Semântico escolher a versão publicada do Projeto, em seguida campos e medidas governadas;
5. definir linhas máximas, timeout e parâmetros apenas quando necessário;
6. salvar: o arquivo data/<chiave>.resource.json é criado e associado ao widget selecionado.

O modo SQL custom avançado é reservado para consultas read-only que não são expressíveis pelo configurador. Requer também a declaração das colunas de saída. Joins, filtros ou ordenações complexos podem ser refinados abrindo o JSON gerado no modo Código.

O navegador não recebe as credenciais e não consulta diretamente a fonte. Consultas, parâmetros, limites e autorizações são reavaliados na execução.

Dados e integrações Sybot

Os recursos de dados podem usar fontes e Modelos Semânticos autorizados. As consultas são somente leitura e respeitam novamente as permissões do usuário no momento da execução.

No widget Formulário de dados, é obrigatório um Workflow do Projeto. Cada parâmetro pode usar um campo do formulário, o valor padrão do Workflow ou um valor fixo não sensível. Os campos Lista de valores desativam padrão, mínimo e máximo e só podem ser associados a parâmetros Workflow do mesmo tipo. O editor importa rótulos e valores do Workflow e mostra um menu suspenso no Portal. Valores fixos não estão disponíveis para estes parâmetros: a opção escolhida é validada e enviada diretamente ao Workflow.

No widget Vista Utente, escolher na lista suspensa uma vista publicada do Projeto do Portal. A seleção registra automaticamente tanto a vista quanto a versão publicada fixada.

No widget Ação Workflow, escolher um Workflow executável do Projeto. Para cada parâmetro indicar se usar o valor padrão, solicitar o valor ao usuário ou salvar um valor fixo. Parâmetros sensíveis podem ser solicitados apenas em tempo de execução; Workflows com parâmetros de arquivo, não suportados, não são selecionáveis. Na Preview é executada apenas a verificação da configuração.

Escrever um widget custom

Adicionando Widget custom sandbox, o editor cria uma pasta explícita:

components/<chiave>/
├── component.json
├── template.html
├── styles.css
└── index.js

Abra código componente passa para Código e abre todos os quatro arquivos. template.html contém o markup, styles.css o estilo isolado, index.js exporta mount(sdk) e component.json declara arquivos e capability. O código pode modificar o DOM do próprio iframe, reagir a eventos e usar PortalWidgetSDK para dados, navegação interna e Workflows autorizados. Não pode acessar o documento pai, à sessão, a outros widgets, a cookies ou à rede direta.

Em template.html, styles.css e index.js, o editor oferece preenchimento contextual durante a digitação; ele também pode ser aberto com Ctrl+Espaço ou Cmd+Espaço. Depois de sdk., são mostrados apenas os métodos permitidos pelas capability do component.json atual. A margem sinaliza erros de sintaxe JavaScript, identificadores não definidos, tags HTML não balanceadas e propriedades CSS inválidas sem interromper o salvamento automático.

Guia de widgets → Widget sandbox custom → SDK Sandbox documenta a assinatura, os parâmetros, o valor retornado, a capability necessária e um exemplo de cada método, incluindo query, emit, navigate, operações de Workflow, invalidateData, setContext, getContext e onDataInvalidated.

Após uma mutação, sdk.invalidateData() notifica as Data Resources alteradas. Tabelas e Gráficos associados atualizam-se em segundo plano sem recarregar a página, enquanto sdk.onDataInvalidated() permite ao Custom Widget repetir a consulta. sdk.setContext() atualiza o contexto partilhado e notifica todos os consumidores; sdk.getContext() devolve uma cópia local.

As Data Resources baseadas num Modelo Semântico também são atualizadas quando uma mutação tem origem num recurso direto com uma chave diferente.

Para autorizar a execução, selecione o widget e ative Autorizar o widget a iniciar Workflows no Inspector. O editor atualiza o manifest automaticamente: não é necessário criar um binding na página nem editar JSON. sdk.runWorkflow(nomeOuId, parâmetros) e sdk.startWorkflow(nomeOuId, parâmetros) podem chamar um Workflow executável do Projeto atual; as permissões são verificadas novamente durante a execução.

As solicitações de dados simultâneas de widgets diferentes permanecem independentes e têm um tempo máximo. Se o código do widget não tratar um erro durante a inicialização, o Portal encerra o carregamento e mostra uma mensagem dentro do widget.

Power BI e Qlik

Relatório Power BI suporta Secure URL com a sessão Microsoft do leitor e App owns data com perfil e associação governados pelo Projeto. Dashboard Qlik suporta Secure URL e OAuth impersonation com qlik-embed. Nos dois casos, os segredos permanecem na configuração administrativa e o widget guarda apenas URL ou associação lógica. Execute Diagnóstico antes da Pré-visualização e teste permissões, licença e políticas do provedor no domínio publicado.

Consulte Integrações governadas para o procedimento completo.

Validar e testar o rascunho

1. Salvar o arquivo ou aplicar as propriedades do composer.
2. Selecionar Validar.
3. Corrigir os elementos listados no painel Problemas.
4. Selecionar Build para verificar a construção do rascunho.
5. Selecionar Preview e testar layout, dados e interações.

A Preview é separada da versão publicada. Os erros exibem uma mensagem utilizável e, quando disponível, um identificador para comunicar ao suporte.

Para acessos e ciclo de publicação consultar Pubblicazione e accessi.