Reference dei widget dei Portali

Questa pagina descrive i widget inclusi nel catalogo iniziale. Le proprietà si modificano nell’Inspector come oggetto JSON; titolo, geometria e stile comune dispongono anche di controlli visuali.

Proprietà comuni

Proprietà	Tipo	Uso
title	stringa	Titolo opzionale del widget.
hidden	booleano	Nasconde il widget quando impostato a true.
placement.x, placement.y	intero	Posizione nella griglia, a partire da 1.
placement.w, placement.h	intero	Larghezza e altezza in celle.
style	oggetto	Proprietà CSS, stati e breakpoint dell’istanza.
style.rawCss	stringa	Regole CSS scoped avanzate.

Nell’Inspector il campo Titolo e la proprietà JSON title sono sincronizzati in entrambe le direzioni. Una stringa inserita in uno dei due viene riportata anche nell’altro. Per rimuovere l’intestazione, eliminare title dal JSON oppure svuotare Titolo; il controllo guidato salva automaticamente la modifica.

I controlli guidati vengono salvati automaticamente e mostrano un toaster di conferma. Per Proprietà JSON, Stile JSON e CSS scoped usare invece Salva modifiche avanzate.

Sezione (layout.section)

Raggruppa contenuti correlati. title controlla l’intestazione visibile. È utile anche come struttura di destinazione per componenti custom.

Testo (content.text)

La proprietà text contiene il testo semplice; le interruzioni di riga vengono conservate.

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

Per cambiare solo il contenuto, usare .portal-text nel CSS scoped.

Hero (content.hero)

Blocco di apertura con eyebrow, title, subtitle, immagine (assetPath) e pulsante facoltativo (buttonLabel, routeId). routeId accetta soltanto una rotta interna. Usare un solo Hero principale per pagina e compilare imageAlt quando è presente l’immagine.

Card (content.card)

Combina title, text, immagine e collegamento interno. Nelle griglie usare dimensioni uniformi; .portal-card__media permette di regolare aspect ratio e object-fit.

Divisore (content.divider)

orientation può essere horizontal o vertical; title è un’etichetta facoltativa. Un divisore verticale richiede un’altezza di griglia adeguata.

Collegamento (navigation.link)

• label: etichetta del pulsante;
• routeId: identificativo di una rotta interna dichiarata in portal.json.

Il widget non apre URL esterni.

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

Menu (navigation.menu)

items è un array di {label, routeId} selezionato dalle rotte esistenti. orientation può essere horizontal o vertical; collapseOnMobile abilita la modalità compatta sugli schermi piccoli.

Schede di navigazione (navigation.tabs)

Mostra rotte correlate come schede. items conserva l’ordine, mentre stretch distribuisce le schede sulla larghezza disponibile. Su mobile le schede scorrono orizzontalmente.

Breadcrumb (navigation.breadcrumb)

items descrive il percorso gerarchico; l’ultima voce può non avere routeId. separator accetta un testo breve. Il Breadcrumb non sostituisce il menu principale.

Immagine (media.image)

• assetPath: percorso dell’immagine nel repository;
• alt: descrizione alternativa accessibile.

Caricare prima il file dall’Explorer e poi usare lo stesso percorso:

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

Sono caricabili PNG, JPEG, GIF e WebP fino al limite indicato dall’editor. L’altezza placement.h dimensiona anche l’immagine, che usa tutto lo spazio disponibile senza deformarsi. Per cambiare il ritaglio usare, per esempio, .portal-image { object-fit: cover; } nel CSS scoped.

Modulo sola lettura (form.readonly)

fields è un array di oggetti con key, label e value:

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

Pannello collassabile (layout.collapsible)

title resta sempre visibile, content contiene il testo e openByDefault sceglie lo stato iniziale. Non nascondere in un pannello chiuso errori o conferme obbligatorie.

Sidebar (layout.sidebar)

Area laterale confinata nel widget. side è left o right; collapsible e collapsedByDefault governano il controllo compatto. Per una navigazione completa usare preferibilmente un Menu verticale.

Drawer (layout.drawer)

Pannello sovrapposto aperto da buttonLabel. side sceglie il lato e closeOnScrim abilita la chiusura sullo sfondo. Il runtime gestisce Escape e restituzione del focus; non usare il Drawer per messaggi bloccanti.

Tabella dati (data.table)

• columns: elenco ordinato delle chiavi da mostrare;
• bindings.data.resourceKey: Data Resource dichiarata nella cartella data.

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

La Data Resource può interrogare oggetti autorizzati, sorgenti dati o Modelli Semantici. Il browser non accede direttamente alla sorgente.

Il comando Dati crea e modifica la risorsa con selezione visuale di connessione, schema, tabella, dimensioni, misure e aggregazioni, oppure di Modello Semantico pubblicato, campi e misure. Apri JSON consente le configurazioni avanzate dopo il primo salvataggio.

Modulo dati (form.write)

Raccoglie campi tipizzati e li salva in un Working Dataset associato. Il binding deve consentire l’aggiunta di record; la validazione viene ripetuta sul server e il browser non accede direttamente all’archivio. Dopo un salvataggio riuscito, tabelle e grafici collegati vengono aggiornati senza ricaricare la pagina.

Grafico a barre (data.chart)

Mostra metriche calcolate sul server come barre orizzontali accessibili. series elenca chiave, etichetta e colore facoltativo di ogni metrica; il binding deve riferirsi a una Data Resource aggregata.

Export dati (data.export)

Espone CSV e XLSX soltanto quando la Data Resource autorizza l’export. Il file generato è temporaneo, rispetta i permessi del lettore e neutralizza i valori potenzialmente pericolosi per i fogli di calcolo.

Vista Utente (user-view.embed)

• viewId: ID della Vista Utente;
• versionId: ID della versione pubblicata da bloccare nella release.

Entrambi i valori sono obbligatori. In modalità Visuale la tendina mostra solo le Viste Utente pubblicate appartenenti al Progetto del Portale e compila automaticamente entrambi gli ID. Il pin della versione evita che una modifica successiva della Vista cambi una release Portale già approvata.

In Anteprima e nel Portale pubblicato la Vista viene mostrata direttamente nel widget, senza richiedere un secondo accesso. Se la sessione o le autorizzazioni non sono più valide, il widget mostra una diagnostica al posto della Vista.

Nel Portale la testata estesa della Vista non occupa spazio: aggiornamento, filtri e visualizzazione sono raccolti in una barra flottante a sole icone.

Widget Vista Utente (user-view.widget)

Incorpora un solo widget standard o custom di una Vista pubblicata. Dopo aver aggiunto Widget Vista Utente dalla palette, l’Inspector mostra soltanto le Viste accessibili nel Progetto e i relativi widget pubblicati, quindi registra viewId, versionId e widgetKey. Sono supportati anche grafici, KPI, tabelle, mappe e widget provenienti dal catalogo custom delle Viste.

Il runtime carica soltanto la porzione della Vista e la sorgente dati necessarie al widget selezionato; non è possibile cambiare widgetKey per accedere a una sorgente differente.

Tipologie native condivise con le Viste Utente

Il Portale può creare ex novo le tipologie disponibili anche nell’editor delle Viste Utente. La palette presenta la tipologia, non le istanze già configurate nelle singole Viste. Le nuove istanze appartengono al Portale e usano proprietà, guida e renderer condivisi.

Le famiglie disponibili comprendono:

• grafici a barre, linee, area, torta e donut;
• mappe a cluster e coropletiche, KPI e dettaglio record;
• Titolo sezione, HTML sicuro, Immagine, Separatore, Pannello e Schede;
• Navigatore pagine e controlli per aggiornamento, filtri, visibilità e stato;
• Avvia Workflow, Azione multipla, stato, log e console Workflow;
• Diagnostica vista.

Le tipologie dati richiedono una Data Resource configurata nel Portale; le tipologie che avviano un Workflow richiedono il relativo binding. I nomi già presenti nel catalogo Portal, come Testo o Tabella dati, mantengono la propria implementazione Portal.

Azione Workflow (workflow.action)

• workflowId: Workflow associato;
• buttonLabel: testo del pulsante;
• confirmationText: conferma opzionale;
• fields: parametri raccolti prima dell’avvio;
• bindings.workflow.workflowId: deve coincidere con props.workflowId.

In modalità Visuale la tendina mostra solo i Workflow eseguibili del Progetto del Portale. Per ogni parametro l’Inspector genera una scelta tra valore predefinito (default), richiesta all’utente (prompt) e valore fisso (literal). I parametri sensibili non ammettono valori fissi; i Workflow con parametri file non sono selezionabili.

In Preview l’azione esegue un dry-run. Nel Portale attivo avvia il Workflow solo se utente, Portale e release sono autorizzati.

Diagramma BPMN (bpmn.viewer)

• templateId: BPMN appartenente al Progetto;
• versionId: versione deployata e pinned.

La tendina compila entrambi i valori e mostra soltanto diagrammi accessibili. Preview e runtime usano un viewer read-only e rivalidano i permessi del lettore.

Report Power BI (bi.powerbi)

Il widget supporta sia Secure URL, con sessione Microsoft del lettore, sia App owns data, con profilo e binding governati dal Progetto. Gli URL Publish to web e i valori che contengono token o credenziali vengono rifiutati. La configurazione completa dei due modi è descritta nella sezione Power BI: Secure URL e App owns data.

Dashboard Qlik (bi.qlik)

• embedMode: secure_url oppure oauth_impersonation;
• embedUrl: URL HTTPS Qlik, soltanto per Secure URL;
• bindingKey: binding logico del Progetto, soltanto per OAuth impersonation;
• allowFullscreen: abilita il fullscreen.

La modalità governata configura App ID e tipo di contenuto nel binding e usa un token breve generato da Sybot. Profilo ed endpoint devono superare la diagnostica e la release conserva la revisione del binding. Per la procedura consultare Integrazioni governate.

Widget custom sandbox (custom.sandbox)

Una componente custom usa questa struttura:

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

component.json dichiara file e capability:

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

Il JavaScript può modificare il DOM interno al proprio iframe. Per dati e azioni usa PortalWidgetSDK; chiamate di rete dirette, accesso al documento padre, cookie e storage della sessione non sono consentiti.

L’Inspector espone Apri codice componente, che passa automaticamente a Codice e apre manifest, template, CSS e JavaScript. Il catalogo di Progetto può anche copiare una componente da un altro Portale; il componente diventa una copia versionabile nel repository corrente.

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

Stile, stati e breakpoint

Le proprietà CSS usano nomi kebab-case. Le sezioni states e breakpoints applicano variazioni locali:

{
  "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"}
  }
}

Gli stati supportati sono hover, focus, active e disabled; i breakpoint sono sm, md, lg e xl. Verificare sempre Desktop, Tablet, Mobile e Preview.

Power BI: Secure URL e App owns data

Il widget bi.powerbi offre due modalità:

• Secure URL usa il collegamento reportEmbed e la sessione Microsoft del lettore. Se il lettore non è già autenticato, la schermata di login è prevista.
• App owns data usa un binding Power BI del Progetto. Sybot ottiene un token temporaneo sul server; credenziali e token non vengono salvati nel widget.

Per App owns data, un Super Admin crea prima il secret nella tab Credential Vault del Control Center. Il proprietario del Progetto apre poi Gestisci profili e report nel Portal Editor, crea un profilo, un binding e almeno l'endpoint Authoring. Le tendine consentono di caricare workspace e report accessibili al profilo. Usare Diagnostica prima della Preview.

Ogni Progetto può usare più profili, anche per tenant o utenti Power BI diversi, e scegliere il profilo per ogni endpoint. Sono disponibili Microsoft public cloud, US Government GCC e Power BI China. Il Vault consente ambito di installazione o Progetto, scadenza, rotazione, disabilitazione e revoca definitiva. RLS si configura con identità Sybot, valore statico e ruoli; le impostazioni SDK avanzate restano facoltative.

Proprietà	Uso
embedMode	secure_url oppure app_owns_data.
embedUrl	URL reportEmbed, soltanto per Secure URL.
reportBindingKey	Binding logico del Progetto, soltanto per App owns data.
variantKey	Variante dell'endpoint, normalmente default.
pageName	Pagina iniziale facoltativa.
showFilters	Mostra o nasconde il pannello filtri.
showPageNavigation	Mostra o nasconde la navigazione pagine.

Un binding può risolvere report e identità diversi in Authoring, Development, Staging, Production o su un target specifico. La rotazione di un secret nel Vault non richiede la modifica del widget. Il token di embed viene rinnovato automaticamente prima della scadenza.

Prima del deployment, ogni binding e variante App owns data della release deve avere un endpoint diagnosticato per il target o per il fallback del suo ambiente. Se manca, il preflight blocca il deploy indicando la configurazione da correggere; Secure URL non richiede questo controllo.