Reference dei widget dei Portali

Questa pagina descrive i widget inclusi nel catalogo iniziale. I widget core dispongono di controlli visuali e, quando previsto, di proprietà JSON avanzate; le tipologie native delle Viste Utente si configurano invece interamente con controlli guidati.

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. Layout immagine può mostrare l’immagine come sfondo oppure in alto, al centro o in basso; in ogni modalità il ritaglio resta proporzionato e si adatta alla larghezza disponibile.

Card (content.card)

L’Inspector separa contenuti, media e azioni in sezioni richiudibili. La Card può mostrare sovratitolo, titolo, sottotitolo e testo; icona e immagine sono facoltative e indipendenti. Le azioni sono ripetibili e riordinabili, possono aprire rotte interne o URL HTTPS e avere ruolo e icona propri.

Nel tab Stile si configurano layout dell’immagine (alto, sinistra, destra o sfondo), posizione dell’icona, tipografia combinabile, allineamenti, contenitore e aspetto comune dei pulsanti. Le Card create in precedenza restano compatibili.

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)

La tabella legge una Data Resource autorizzata e aggiorna righe, stato e paginazione senza ricaricare la pagina. Nell’Inspector sono disponibili:

• Sorgente dati: seleziona la Data Resource dichiarata nella cartella data; il browser non accede direttamente alla sorgente;
• Colonne: sceglie e ordina le colonne visibili. Per i Modelli Semantici mostra le etichette funzionali di entità, campi e misure, conservando internamente le chiavi di output necessarie alla query;
• Righe per pagina: accetta un valore da 1 a 200. Il runtime mostra intervallo corrente, totale, pagina, pulsanti precedente e successiva;
• Colonna e direzione di ordinamento: applicano l’ordinamento iniziale ASC o DESC tramite il Portal Gateway;
• Eventi di selezione: none non rende le righe selezionabili; single evidenzia una riga e pubblica l’evento data.table.rowSelected, con la riga, il suo indice nella pagina e il numero di pagina;
• Messaggio stato vuoto: sostituisce il testo mostrato quando la query non restituisce righe.

{
  "props": {
    "title": "Ordini",
    "columns": ["number", "status"],
    "pageSize": 25,
    "sortColumn": "number",
    "sortDirection": "DESC",
    "rowSelection": "single"
  },
  "bindings": {"data": {"resourceKey": "orders"}}
}

La Data Resource può interrogare oggetti autorizzati, sorgenti dati o Modelli Semantici. La paginazione viene eseguita dal provider quando la sorgente è server-side; il widget usa sempre lo stesso controllo e mostra il totale restituito dal Gateway.

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.

Per ascoltare una selezione, collegare l’evento data.table.rowSelected nel flusso eventi del Portale. Il payload contiene row, index e page; non usare l’indice come identificativo stabile, ma leggere dalla riga una chiave funzionale restituita dalla Data Resource.

Modulo dati (form.write)

Raccoglie campi tipizzati e avvia un Workflow autorizzato. La configurazione avviene interamente dall’Inspector:

• Definisci campi apre una modale dedicata per key, etichetta, tipo, valore predefinito, obbligatorietà, min e max. Occorre almeno un campo; i limiti si attivano soltanto per numeri, date e data/ora;
• per i campi string, Testo multilinea permette di inserire testo su più righe e di scegliere quante righe mostrare (5 per impostazione predefinita). Il valore viene inviato al Workflow come stringa;
• Etichetta pulsante personalizza l’azione di invio;
• Messaggio di successo descrive l’accettazione dell’operazione;
• Workflow è obbligatorio e mostra soltanto i Workflow eseguibili del Progetto che ricevono dati in input;
• per ogni parametro del Workflow, Sorgente valore consente di usare il valore predefinito, un campo del modulo o un valore fisso non sensibile.

Il tipo Lista valori usa le opzioni configurate nel Workflow e viene renderizzato come menu a tendina. Non espone default, min o max, non accetta un valore fisso e può essere associato soltanto a un parametro Workflow dello stesso tipo. Etichette e valori delle opzioni restano distinti e la scelta viene validata prima dell’avvio.

Il valore predefinito del Workflow e il valore fisso richiedono entrambi un campo del modulo associato. In Preview sovrascrivono l’eventuale default e sono mostrati direttamente nel relativo input disabilitato, senza una riga testuale aggiuntiva. Il pulsante invia i campi al servizio Workflow, che applica mapping, tipi, permessi e idempotenza prima dell’esecuzione. Il modulo mostra dinamicamente l’avvio riuscito o una diagnostica con codice di correlazione in caso di errore.

Il Modulo dati non richiede una Data Resource e la relativa sezione non è presente nell’Inspector. Quando si aggiorna una configurazione precedente, l’editor rimuove automaticamente l’eventuale binding dati residuo.

Esempio: un modulo con campo customer_id può associare quel campo al parametro Workflow customerId; un parametro origin può invece ricevere il valore fisso portal. La persistenza finale rimane responsabilità del Workflow.

Grafico a barre (data.chart)

Mostra una misura già elaborata dalla Data Resource per una dimensione, con barre verticali. Nell'Inspector puoi scegliere una dimensione e una misura; selezionando un altro campo sostituisci quello precedente. Il grafico non aggiunge aggregazioni automatiche ai dati ricevuti.

Puoi configurare formato dei valori, scala, assi, griglia, ordinamento, colori, etichette, tooltip e linea di riferimento. Se non sono disponibili valori validi viene mostrato il messaggio di stato vuoto configurato.

Per i grafici creati con versioni precedenti, il Designer segnala quando è necessario un adeguamento e mostra quali selezioni saranno conservate o rimosse. L'adeguamento richiede una conferma esplicita. Completa la scelta di dimensione e misura per salvare la pagina. Anche il grafico visualizzato segnala quando la configurazione precedente richiede un adeguamento.

Carica File (form.upload)

Consente al lettore di trascinare un documento nell’area di caricamento oppure di selezionarlo dal dispositivo. Durante l’operazione il widget aggiorna lo stato senza ricaricare la pagina; al termine mostra nome, dimensione e comando di rimozione. Il pulsante Download è disponibile soltanto quando abilitato nell’Inspector.

La configurazione permette di scegliere le estensioni ammesse tra PDF, PNG, JPG/JPEG, DOCX, TXT, CSV e XLSX, impostare la dimensione massima da 1 a 256 MB e attivare Cifra file sul server. Il limite del widget viene sempre applicato insieme al limite assoluto di 256 MB.

Il formato dichiarato non è sufficiente: prima del salvataggio Sybot verifica il contenuto reale del file e rifiuta eseguibili, script mascherati e documenti che non corrispondono all’estensione. In caso di errore il widget mostra una spiegazione utilizzabile e, quando disponibile, il codice diagnostico. Ogni lettore può scaricare o rimuovere soltanto i file che ha caricato.

Export dati (data.export)

Le checkbox dell’Inspector permettono di esporre CSV, XLSX o entrambi; almeno un formato deve restare selezionato. Non serve abilitare un comando di export nella Data Resource: sono supportate Connessioni, Modelli Semantici e Working Dataset interrogabili. Binding del widget, accesso al Portale e permessi sulla sorgente vengono comunque verificati. Il file generato è temporaneo 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. L’Inspector organizza le proprietà in sezioni e offre controlli visuali per colonne, widget collegati, soglie, intervalli e mapping: non occorre modificare il JSON. Le sezioni mantengono lo stato aperto o chiuso durante l’autosalvataggio.

Sono disponibili anche le tipologie con un omonimo nel catalogo Portal, tra cui Tabella dati. La voce nativa Vista Utente è distinta da quella core, che mantiene invariati implementazione e comportamento.

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 avvia realmente il Workflow sull’istanza Sybot corrente, applicando gli stessi controlli su utente, Portale e binding. La testata della Preview segnala questo comportamento: usare dati di test e considerare reali anche gli eventuali effetti sui sistemi collegati.

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 i nuovi profili, ogni utente Sybot deve essere associato esplicitamente al proprio userId Qlik o subject IdP prima di aprire il widget. 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;
}

Per aggiornamenti live, registrare sdk.onDataInvalidated(listener) e ripetere la query quando l’evento include la risorsa usata dal widget. Dopo una mutazione chiamare sdk.invalidateData(resourceKey); setContext() e getContext() gestiscono il contesto condiviso senza accedere al documento padre.

Per aggiungere o rimuovere la capability workflow:start, usare Autorizza il widget al lancio dei Workflow nell’Inspector. Non è necessario modificare il manifest o creare bindings.workflow nella pagina. Il componente può quindi usare lo stesso SDK anche in Preview, indicando il nome visibile o l’ID di qualsiasi Workflow eseguibile del Progetto:

const execution = await sdk.runWorkflow('Importa clienti', parameters);
const status = await sdk.workflowStatus(execution.executionId);
const tasks = await sdk.workflowLog(execution.executionId);

startWorkflow() è l’alias compatibile di runWorkflow(); stopWorkflow(executionId) richiede la stessa autorizzazione di avvio. Stato e log restano disponibili durante la sessione di Preview per facilitare il test. Il server limita sempre la risoluzione al Progetto del Portale e ai ruoli dell’utente; se più Workflow hanno lo stesso nome occorre usare l’ID.

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.