Referência dos widgets dos Portais

Esta página descreve os widgets incluídos no catálogo inicial. As propriedades modificam-se no Inspector como objeto JSON; título, geometria e estilo comum dispõem também de controlos visuais.

Propriedades comuns

Propriedade	Tipo	Uso
title	stringa	Título opcional do widget.
hidden	booleano	Esconde o widget quando definido como true.
placement.x, placement.y	inteiro	Posição na grelha, a partir de 1.
placement.w, placement.h	inteiro	Largura e altura em células.
style	objeto	Propriedades CSS, estados e breakpoint da instância.
style.rawCss	stringa	Regras CSS scoped avançadas.

No Inspector, o campo Título e a propriedade JSON title são sincronizados em ambas as direções. Uma string inserida em um dos dois é refletida também no outro. Para remover o cabeçalho, elimine title do JSON ou esvazie Título; o controlo guiado guarda automaticamente a alteração.

Os controlos guiados são guardados automaticamente e mostram um toaster de confirmação. Para Propriedades JSON, Estilo JSON e CSS scoped usar em vez disso Guardar alterações avançadas.

Secção (layout.section)

Agrupa conteúdos relacionados. title controla o cabeçalho visível. É útil também como estrutura de destino para componentes custom.

Texto (content.text)

A propriedade text contém o texto simples; as quebras de linha são conservadas.

{"title": "Avviso", "text": "Intervento programmato\nDalle 18:00 alle 19:00"}

Para alterar apenas o conteúdo, usar .portal-text no CSS scoped.

Hero (content.hero)

Bloco de abertura com eyebrow, title, subtitle, imagem (assetPath) e botão opcional (buttonLabel, routeId). routeId aceita apenas uma rota interna. Usar um único Hero principal por página e preencher imageAlt quando existe a imagem.

Card (content.card)

Combina title, text, imagem e ligação interna. Nas grelhas usar dimensões uniformes; .portal-card__media permite ajustar aspect ratio e object-fit.

Divisor (content.divider)

orientation pode ser horizontal ou vertical; title é uma etiqueta opcional. Um divisor vertical requer uma altura de grelha adequada.

Ligação (navigation.link)

• label: etiqueta do botão;
• routeId: identificador de uma rota interna declarada em portal.json.

O widget não abre URLs externos.

{"label": "Apri ordini", "routeId": "orders"}

Menu (navigation.menu)

items é um array de {label, routeId} selecionado das rotas existentes. orientation pode ser horizontal ou vertical; collapseOnMobile habilita o modo compacto em ecrãs pequenos.

Guias de navegação (navigation.tabs)

Mostra rotas relacionadas como guias. items conserva a ordem, enquanto stretch distribui as guias pela largura disponível. No mobile as guias deslizam horizontalmente.

Breadcrumb (navigation.breadcrumb)

items descreve o caminho hierárquico; o último item pode não ter routeId. separator aceita um texto curto. O Breadcrumb não substitui o menu principal.

Imagem (media.image)

• assetPath: caminho da imagem no repositório;
• alt: descrição alternativa acessível.

Carregar primeiro o ficheiro do Explorer e depois usar o mesmo caminho:

{"title": "Marchio", "assetPath": "assets/logo.png", "alt": "Logo aziendale"}

São carregáveis PNG, JPEG, GIF e WebP até ao limite indicado pelo editor. A altura placement.h dimensiona também a imagem, que usa todo o espaço disponível sem se deformar. Para alterar o recorte usar, por exemplo, .portal-image { object-fit: cover; } no CSS scoped.

Formulário de leitura única (form.readonly)

fields é um array de objetos com key, label e value:

{
  "title": "Ordine",
  "fields": [
    {"key": "number", "label": "Numero", "value": "SO-1001"},
    {"key": "status", "label": "Stato", "value": "Aperto"}
  ]
}

Painel colapsável (layout.collapsible)

title é sempre visível, content contém o texto e openByDefault escolhe o estado inicial. Não oculte em um painel fechado erros ou confirmações obrigatórias.

Barra lateral (layout.sidebar)

Área lateral confinada no widget. side é left ou right; collapsible e collapsedByDefault governam o controlo compacto. Para uma navegação completa, use preferencialmente um Menu vertical.

Gaveta (layout.drawer)

Painel sobreposto aberto por buttonLabel. side escolhe o lado e closeOnScrim habilita o fechamento no fundo. O runtime gerencia Escape e restauração do foco; não use o Drawer para mensagens bloqueantes.

Tabela de dados (data.table)

• columns: lista ordenada das chaves a exibir;
• bindings.data.resourceKey: Data Resource declarada na pasta data.

{
  "props": {"title": "Ordini", "columns": ["number", "status"]},
  "bindings": {"data": {"resourceKey": "orders"}}
}

A Data Resource pode consultar objetos autorizados, fontes de dados ou Modelos Semânticos. O navegador não acede diretamente à fonte.

O comando Dados cria e altera a recurso com seleção visual de conexão, esquema, tabela, dimensões, medidas e agregações, ou de Modelo Semântico publicado, campos e medidas. Abrir JSON permite as configurações avançadas após o primeiro salvamento.

Formulário de dados (form.write)

Recolhe campos tipados e guarda-os num Working Dataset associado. O binding deve permitir adicionar registos; a validação é repetida no servidor e o navegador nunca acede diretamente ao armazenamento. Depois de uma gravação bem-sucedida, as tabelas e os gráficos ligados são atualizados sem recarregar a página.

Gráfico de barras (data.chart)

Mostra métricas calculadas no servidor como barras horizontais acessíveis. series indica a chave, etiqueta e cor opcional de cada métrica; o binding deve referir uma Data Resource agregada.

Exportação de dados (data.export)

Disponibiliza CSV e XLSX apenas quando a Data Resource autoriza a exportação. O ficheiro gerado é temporário, respeita as permissões do leitor e neutraliza valores potencialmente perigosos para folhas de cálculo.

Vista do Utilizador (user-view.embed)

• viewId: ID da Vista do Utilizador;
• versionId: ID da versão publicada a bloquear na release.

Ambos os valores são obrigatórios. No modo Visual, a tendina exibe apenas as Visualizações de Utilizador publicadas que pertencem ao Projeto do Portal e preenche automaticamente ambos os IDs. O pin da versão impede que uma alteração subsequente da Visualização altere uma release do Portal já aprovada.

Na Pré-visualização e no Portal publicado, a Vista é exibida diretamente no widget, sem exigir um segundo acesso. Se a sessão ou as autorizações não forem mais válidas, o widget exibe uma diagnóstico em vez da Vista.

No Portal, o cabeçalho expandido da Visão não ocupa espaço: atualização, filtros e visualização são reunidos em uma barra flutuante com apenas ícones.

Widget Vista Utilizador (user-view.widget)

Incorpora um único widget padrão ou personalizado de uma Vista publicada. A paleta e o Inspector mostram apenas widgets das Vistas acessíveis no Projeto e registram viewId, versionId e widgetKey. São suportados também gráficos, KPI, tabelas, mapas e widgets provenientes do catálogo personalizado das Vistas.

O runtime carrega apenas a parte da Vista e a fonte de dados necessárias para o widget selecionado; não é possível alterar widgetKey para aceder a uma fonte diferente.

Ação Workflow (workflow.action)

• workflowId: Fluxo de trabalho associado;
• buttonLabel: texto do botão;
• confirmationText: confirmação opcional;
• fields: parâmetros recolhidos antes do arranque;
• bindings.workflow.workflowId: deve coincidir com props.workflowId.

Nella modalità Visuale, a tendina mostra apenas os Workflows executáveis do Projeto do Portal. Para cada parâmetro, o Inspector gera uma escolha entre valor padrão (default), solicitado ao usuário (prompt) e valor fixo (literal). Parâmetros sensíveis não admitem valores fixos; Workflows com parâmetros de arquivo não são selecionáveis.

Em Preview, a ação executa um dry-run. No Portal ativo, inicia o Workflow apenas se o usuário, o Portal e a release estiverem autorizados.

Diagrama BPMN (bpmn.viewer)

• templateId: BPMN pertencente ao Projeto;
• versionId: versão deployed e pinned.

A lista preenche ambos os valores e mostra apenas diagramas acessíveis. A Pré-visualização e o runtime usam um viewer read-only e voltam a validar as permissões do leitor.

Relatório Power BI (bi.powerbi)

O widget suporta Secure URL, com a sessão Microsoft do leitor, e App owns data, com um perfil e uma associação governados pelo Projeto. Os URL Publish to web e os valores com tokens ou credenciais são rejeitados. Consulte Power BI: Secure URL e App owns data para ver a configuração completa dos dois modos.

Dashboard Qlik (bi.qlik)

• embedMode: secure_url ou oauth_impersonation;
• embedUrl: URL HTTPS Qlik, apenas para Secure URL;
• bindingKey: associação lógica do Projeto, apenas para OAuth impersonation;
• allowFullscreen: ativa o modo de ecrã inteiro.

O modo governado guarda App ID e tipo de conteúdo na associação e usa um token temporário gerado pelo Sybot. Perfil e endpoint devem passar no Diagnóstico e a release conserva a revisão da associação. Consulte Integrações governadas.

Widget custom sandbox (custom.sandbox)

Uma componente custom usa esta estrutura:

components/my-widget/
├── component.json
├── template.html
├── styles.css
└── index.js

component.json declara ficheiros e capability:

{
  "schemaVersion": 1,
  "name": "My widget",
  "executionMode": "sandboxed",
  "template": "template.html",
  "styles": "styles.css",
  "entry": "index.js",
  "capabilities": ["data:query", "events:emit"]
}

O JavaScript pode modificar o DOM interno ao seu próprio iframe. Para dados e ações usa PortalWidgetSDK; chamadas de rede diretas, acesso ao documento pai, cookies e armazenamento de sessão não são permitidos.

O Inspector expõe Abrir código componente, que passa automaticamente para Código e abre manifest, template, CSS e JavaScript. O catálogo de Projeto pode também copiar uma componente de outro Portal; a componente torna-se uma cópia versionável no repositório atual.

export async function mount(sdk) {
  const result = await sdk.query('orders', {status: 'open'});
  document.querySelector('[data-count]').textContent = result.rows.length;
}

Estilo, estados e breakpoint

As propriedades CSS usam nomes kebab-case. As secções states e breakpoints aplicam variações locais:

{
  "background-color": "#ffffff",
  "padding": "1rem",
  "border-radius": "8px",
  "states": {
    "hover": {"box-shadow": "0 8px 24px rgba(15, 23, 42, .18)"}
  },
  "breakpoints": {
    "md": {"padding": "1.5rem"}
  }
}

Os estados suportados são hover, focus, active e disabled; os breakpoint são sm, md, lg e xl. Verificar sempre Desktop, Tablet, Mobile e Preview.

Power BI: Secure URL e App owns data

O widget bi.powerbi oferece dois modos:

• Secure URL usa uma ligação reportEmbed e a sessão Microsoft do leitor. A página de início de sessão é esperada quando o leitor ainda não está autenticado.
• App owns data usa uma associação Power BI do Projeto. O Sybot obtém um token temporário no servidor; credenciais e tokens nunca são guardados no widget.

Para App owns data, um Super Admin cria primeiro o segredo no separador Credential Vault do Control Center. O proprietário do Projeto abre depois Gerir perfis e relatórios no Portal Editor e cria um perfil, uma associação e pelo menos o endpoint Authoring. Os seletores carregam os espaços de trabalho e relatórios acessíveis ao perfil. Execute Diagnóstico antes da Pré-visualização.

Cada Projeto pode usar vários perfis, incluindo tenants ou utilizadores Power BI diferentes, e escolher o perfil de cada endpoint. Estão disponíveis Microsoft public cloud, US Government GCC e Power BI China. O Vault suporta âmbito de instalação ou Projeto, validade, rotação, desativação e revogação definitiva. O RLS é configurado com uma identidade Sybot, um valor estático e funções; as definições avançadas do SDK continuam opcionais.

Propriedade	Utilização
embedMode	secure_url ou app_owns_data.
embedUrl	URL reportEmbed, apenas para Secure URL.
reportBindingKey	Associação lógica do Projeto, apenas para App owns data.
variantKey	Variante do endpoint, normalmente default.
pageName	Página inicial opcional.
showFilters	Mostra ou oculta o painel de filtros.
showPageNavigation	Mostra ou oculta a navegação de páginas.

Uma associação pode resolver relatórios e identidades diferentes para Authoring, Development, Staging, Production ou um destino específico. Rodar um segredo do Vault não exige alterar o widget. O token de incorporação é renovado automaticamente antes de expirar.

Antes do deployment, cada associação e variante App owns data da release deve ter um endpoint diagnosticado para o destino ou para o fallback do respetivo ambiente. Se faltar, o preflight bloqueia o deployment e indica a configuração a corrigir; Secure URL não exige este controlo.