Pular para o conteúdo principal

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.

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.

Explorer e Problemas podem ser recolhidos com o botão no cabeçalho. No Explorer, o chevron junto de cada diretório também 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.

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. Para torná-la navegável, adicione em portal.json uma rota que aponte ao caminho completo da página.

Modo Visual​

O modo Visual disponibiliza paletas, canvas e Inspector. É possível adicionar um widget, selecioná-lo e configurá-lo:

  • título e propriedades;
  • posição, largura e altura na grade;
  • estilos para a instância individual;
  • CSS scoped;
  • renderização Desktop, Tablet e Mobile.

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

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.

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

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.