Editor e widget dei Portali

L’Editor dei Portali combina un repository di file navigabile con un composer visuale. Le due modalità operano sulla stessa bozza: le modifiche visuali aggiornano i sorgenti e le parti gestite direttamente nel codice vengono preservate.

All'apertura, l'Editor mostra in modalità Visuale la prima pagina disponibile. Se il Portale non contiene pagine, apre invece portal.json in modalità Codice.

La barra superiore mostra sempre Gestisci dati: il comando apre il Data Manager e carica le Data Resource del Portale anche quando la pagina è vuota o non è selezionato alcun widget. Il pulsante omonimo nell’Inspector rimane il punto contestuale per associare una risorsa al widget selezionato. L’interfaccia dell’Editor usa il carattere Google Sans Flex; il contenuto dell’editor di codice resta monospaziato.

L’interfaccia dell’Editor segue immediatamente il tema chiaro o scuro scelto in Sybot. Toolbar, pannelli, Inspector e finestre di dialogo cambiano palette senza ricaricare la pagina; il canvas e i widget del Portale mantengono invece il tema e gli stili definiti per il contenuto pubblicato.

I selettori Codice e Visuale si trovano tra il nome del Portale e lo stato di salvataggio. Guida widget precede Esporta nella barra delle azioni. Sui viewport stretti la riga resta unica: le etichette scompaiono progressivamente da destra verso sinistra, lasciando visibili le icone con tooltip e nome accessibile. L’helper per trascinamento e ridimensionamento rimane visibile nella toolbar della Canvas, senza il precedente riepilogo delle scorciatoie da tastiera.

Sul lato sinistro, l’Activity Bar apre alternativamente Aggiungi Widget, Pagine, Immagini, Explorer, Diagnostica e Problemi e Proprietà Portale. L’icona delle proprietà è collocata in fondo alla barra. Un solo pannello è visibile alla volta; selezionando di nuovo l’icona attiva lo si chiude. L’Inspector rimane fisso a destra in modalità Visuale. L’Editor ricorda durante la sessione il pannello aperto e la larghezza scelta per la colonna sinistra.

Aggiungi Widget mostra inizialmente le categorie con il numero di elementi e un chevron. Selezionare una categoria per espandere le relative card; Business Intelligence contiene separatamente Report Power BI e Dashboard Qlik. Il campo Cerca widget filtra nomi, categorie e chiavi tecniche in tempo reale e apre automaticamente i gruppi che contengono risultati.

Il pannello Pagine mantiene in alto Aggiungi Pagina e mostra sotto tutte le pagine del Portale. La pagina aperta è evidenziata; i nomi lunghi vengono abbreviati senza alterare il layout e il nome completo è disponibile al passaggio del mouse. Selezionare una pagina la apre direttamente nella Canvas. Il passaggio a Widget, Explorer o Problemi non cambia la pagina corrente.

Aggiungi Pagina richiede un nome, crea il documento iniziale e lo salva in modo asincrono sotto pages/, quindi lo apre nella Canvas. Per scegliere manualmente il percorso o lavorare sui file resta disponibile il flusso avanzato dell’Explorer. In entrambi i casi l’Editor aggiunge automaticamente la route in portal.json e la voce di navigazione in shell.json; eliminando la pagina rimuove entrambe le associazioni senza ricaricare l’interfaccia.

Il pannello Immagini raccoglie il collegamento al catalogo condiviso, il caricamento dal computer e le immagini già presenti nel Portale. Ogni immagine mostra anteprima e nome e può essere eliminata dopo conferma; la griglia si aggiorna senza ricaricare l’Editor.

Nella Canvas, ogni widget è rappresentato da una card compatta che mostra icona, nome, tipologia, dimensione nella griglia e visibilità su PC, tablet e smartphone. La card conserva colori, sfondo e tipografia configurati, mentre i testi lunghi vengono abbreviati senza coprire i comandi di trascinamento e ridimensionamento. Usare Preview per verificare contenuto e comportamento completi del widget.

Duplica widget crea, nella stessa pagina o in un’altra pagina, un’istanza indipendente. Per un widget custom copia anche tutti i file del componente e le modifiche ai sorgenti non ancora salvate, con una nuova chiave componente. Configurazioni, binding, stile e associazioni esterne vengono preservati; modificare o eliminare la copia non coinvolge l’originale. La copia rimane locale, mantiene la modalità sandboxed/trusted e non eredita il collegamento alla versione firmata del catalogo; la condivisione richiede un salvataggio esplicito nel catalogo. Componente e pagina vengono salvati insieme: in caso di errore la duplicazione viene annullata. Le istanze preesistenti che condividono un componente mantengono tale condivisione.

Ogni copia locale può essere salvata nel catalogo come un package distinto, iniziando dalla versione v1, in qualsiasi ordine. Il pulsante scompare soltanto per il componente già collegato; rimane disponibile per le copie non collegate. In caso di nomi uguali il server aggiunge un suffisso e aggiorna il nome e il manifest nell’editor, preservando i file ausiliari. Il catalogo dei widget custom mostra esclusivamente i package salvati esplicitamente nel catalogo. I componenti locali e le copie non ancora salvate non generano card nel catalogo; rimangono disponibili nella Canvas e nell’Explorer.

Modalità Codice

La modalità Codice mostra:

• Explorer, per cercare, creare, rinominare e organizzare i file;
• Carica immagine, per aggiungere al repository asset PNG, JPEG, GIF o WebP;
• schede per i file aperti;
• editor con evidenziazione per JSON, HTML, CSS e JavaScript;
• stato del salvataggio e numero della revisione corrente;
• pannello Problemi con errori e indicazioni correggibili.

Nell’Explorer, il chevron accanto a ogni directory permette di espandere o comprimere soltanto quel ramo; lo stato delle directory viene mantenuto durante la sessione, mentre una ricerca espande temporaneamente i rami necessari per mostrare le corrispondenze.

Le modifiche vengono salvate in modo asincrono. Se la bozza è stata aggiornata da un’altra sessione, l’editor interrompe il salvataggio e segnala il conflitto: ricaricare la versione corrente prima di riprendere il lavoro.

Quando si chiude o si abbandona l’Editor, la sessione di modifica viene rilasciata immediatamente. Un altro utente può quindi aprire lo stesso Portale in modifica senza attendere la scadenza automatica della sessione precedente.

Usare Checkpoint per fissare una revisione immutabile e riconoscibile della bozza. Un checkpoint non pubblica il Portale.

Aprendo un file che non rappresenta una pagina — per esempio portal.json, una Data Resource, un CSS oppure un file di componente — l’editor passa automaticamente a Codice. Il composer Visuale resta associato soltanto alle pagine e non mostra mai il canvas di un file aperto in precedenza. La modalità scelta per ciascuna pagina viene ricordata nella sessione di editing: se una pagina era aperta in Visuale, dopo aver consultato un file di configurazione la stessa pagina torna automaticamente in Visuale.

Per creare una pagina, selezionare Nuovo file e usare un percorso JSON sotto pages/, per esempio pages/dashboard.json o pages/orders/detail.json. Il nome del file è libero: l’editor genera automaticamente UUID, titolo, layout a griglia e lista dei widget. Per renderla navigabile, aggiungere in portal.json una route che punti al percorso completo della pagina.

Modalità Visuale

La modalità Visuale mette a disposizione palette, canvas e Inspector. Quando si seleziona un widget, l’Inspector apre sempre Proprietà e organizza la configurazione in tre tab:

• Proprietà contiene titolo, dati, sorgenti, binding e opzioni funzionali;
• Stile contiene controlli visuali, Style JSON e CSS scoped;
• Avanzate contiene posizione, larghezza, altezza e Proprietà JSON.

Il cambio tab non deseleziona il widget e non perde i valori correnti, anche durante il salvataggio asincrono. Le stesse tab sono disponibili per widget standard, custom, Viste Utente, BPMN, Power BI e Qlik. È possibile spostarsi tra le tab anche con frecce sinistra/destra, Home ed End.

Le proprietà guidate vengono applicate e salvate quando il controllo cambia; un toaster conferma l’esito. Salva modifiche avanzate serve invece per i riquadri JSON e CSS, nei quali è normale avere contenuto temporaneamente non valido durante la digitazione. Lo stato nella testata distingue modifiche in corso, salvataggio e sorgente salvato.

I campi dell’Inspector dipendono dal widget: rotte, immagini, Viste Utente, Workflow, parametri e Data Resource si scelgono da menu filtrati sul Progetto. I selettori di rotta mostrano soltanto le pagine presenti nella navigazione attiva del Portale e si aggiornano senza richiedere l’apertura manuale dei file. Nel widget Widget Vista Utente, dopo aver scelto la Vista, si seleziona il singolo widget pubblicato da incorporare. I colori possono essere scelti con il picker oppure inseriti come valore CSS o design token.

I preset Viewport dichiarano la dimensione simulata. La toolbar di zoom offre −, +, ripristino al 100% e Adatta. Adatta usa insieme larghezza e altezza disponibili, riducendo uniformemente il canvas e mantenendo le proporzioni della Preview. Un clic sulla percentuale ripristina il 100%; un doppio clic consente di inserire direttamente un valore dal 5% al 200%. Con uno zoom personalizzato si usano le barre di scorrimento per esplorare le parti che non entrano nell’area. Lo zoom modifica soltanto la visualizzazione nell’editor, non la geometria salvata né la resa runtime. Ogni widget mostra anche il badge larghezza × altezza in celle.

Per modificare la geometria di un widget:

• trascinare la maniglia in alto a sinistra per spostarlo;
• trascinare la maniglia nell’angolo in basso a destra per ridimensionarlo;
• usare Alt + freccia per spostarlo di una cella;
• usare Maiusc + Alt + freccia per modificarne larghezza o altezza di una cella.

Per duplicare un widget, seleziona Duplica nell'Inspector e scegli la pagina corrente o un'altra pagina dello stesso Portale. Dopo il salvataggio, la copia viene selezionata nella pagina di destinazione. Se mancano i widget collegati o non c'è spazio, l'editor mostra il motivo. La copia di un widget custom usa lo stesso componente, senza crearne un'altra versione.

Per eliminare un widget, selezionarlo e usare Elimina widget nell’Inspector. In alternativa premere Canc o Backspace quando il cursore non si trova in un campo. L’editor chiede sempre conferma. Per un widget standard viene rimossa la sola istanza selezionata; per un widget custom l'operazione è atomica e rimuove il componente, la cartella components/<chiave>/, tutti i file contenuti e ogni sua istanza nelle pagine del Portale. La stessa azione è disponibile con Elimina widget dal menu opzioni o dal menu contestuale della cartella del componente nell'Explorer.

Quando una regione contiene proprietà non gestite dal composer, l’editor la identifica come gestita dal codice e la conserva durante gli aggiornamenti visuali.

Per configurare la pagina anziché un widget, fare clic su un’area libera dello sfondo del canvas. L’Inspector Stile della pagina consente di impostare colore, sfondo, spaziatura interna e altezza minima; Stile JSON e CSS scoped della pagina restano disponibili per le regolazioni avanzate.

Il pulsante Proprietà Portale apre nella colonna sinistra la configurazione della bozza, lasciando l’Inspector destro disponibile per il widget selezionato. La tab Generale contiene nome, abilitazione del codice trusted e i controlli Mostra Header e Mostra Navigazione. Questi ultimi aggiornano e salvano subito la Shell; la Preview riflette la presenza del titolo e della barra di navigazione. I Portali richiedono sempre autenticazione e non consentono incorporamento esterno: i rispettivi valori sono mostrati ma non modificabili. Per gli Owner, la tab Accesso contiene collaboratori, permessi e audience runtime con checkbox, menu e pulsanti allineati al tema dell’Editor. Il cambio tab conserva i valori non ancora salvati; lettura e salvataggio restano asincroni e mostrano l’esito nello stesso pannello senza ricaricare l’Editor.

Configurare aspetto e CSS

Lo Stile guidato espone colore, sfondo, dimensione del testo, allineamento, spaziatura e raggio del bordo. I valori accettano normale sintassi CSS, per esempio #0f172a, 1rem o 8px.

La Configurazione avanzata consente di usare proprietà CSS in kebab-case, stati e breakpoint:

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

Il campo CSS scoped permette di intervenire su qualunque dettaglio senza influenzare gli altri widget. & rappresenta il contenitore dell’istanza; .portal-text seleziona il contenuto del widget Testo:

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

Selezionare Salva modifiche avanzate per registrare JSON e CSS nella pagina. La Preview mostra la resa compilata definitiva.

Cataloghi del Progetto

I pulsanti Widget custom e Immagini aprono un catalogo unificato. Ogni elemento riporta sempre la provenienza: Portale corrente, altro Portale dello stesso Progetto, Vista Utente pubblicata oppure catalogo condiviso delle Viste. Non vengono mostrati oggetti esterni al Progetto o non accessibili all’utente.

In Widget custom gli elementi sono raggruppati per Portale di origine. Il selettore in alto alterna la vista Card e la vista Tabella; quest'ultima offre ordinamento, selezione multipla e pagine da dieci record. Per ogni widget si sceglie la versione e il menu contestuale permette di inserirla nella pagina, esportarla in JSON, aprire una preview statica oppure eliminarla. La conferma di eliminazione elenca i Portali che la utilizzano. Importa widget carica nel catalogo un JSON esportato da un altro Progetto. Immagini raggruppa invece gli asset per Portale o Vista Utente e offre la cancellazione dalla relativa origine, anch'essa protetta da conferma.

La palette non elenca le singole istanze contenute nelle Viste Utente del Progetto. Al loro posto comprende le stesse tipologie disponibili nell’editor delle Viste — tra cui grafici, mappe, KPI, contenuti, layout, controlli, navigazione e workflow — per creare nuovi widget nativi direttamente nel Portale. Questi widget non dipendono da una Vista o da una sua versione.

Per incorporare un widget già configurato in una Vista pubblicata si aggiunge Widget Vista Utente e lo si configura dall’Inspector. Il riferimento registra Vista, versione pubblicata e chiave del widget; una release rimane quindi stabile anche se la Vista viene modificata in seguito.

Quando si usa un’immagine o un componente proveniente da un altro oggetto, l’editor ne crea una copia nel repository del Portale. Questa materializzazione rende checkpoint, build e release riproducibili; la card del catalogo conserva l’indicazione dell’origine per evitare ambiguità.

Widget disponibili

Il catalogo managed comprende:

• Testo, Hero, Card, Immagine e Divisore;
• Collegamento, Menu, Schede di navigazione e Breadcrumb;
• Sezione, Pannello collassabile, Sidebar e Drawer;
• Modulo sola lettura, Modulo dati, Tabella dati, Grafico a barre ed Export dati;
• grafici a barre, linee, area, torta e donut, mappe, KPI e dettaglio record condivisi con le Viste Utente;
• Titolo sezione, HTML sicuro, Immagine, Separatore, Pannello, Schede e Navigatore pagine condivisi;
• controlli di aggiornamento, filtro, visibilità, filtri attivi e ultimo aggiornamento;
• tipologie Workflow e Diagnostica vista;
• Vista Utente completa e singolo widget di Vista Utente;
• Azione Workflow;
• Report Power BI e Dashboard Qlik;
• Widget custom sandbox.

Ogni widget supporta proprietà di stile, stati visuali e breakpoint. Il CSS scoped consente di personalizzare anche hover, focus, stato attivo e stato disabilitato senza modificare gli altri componenti della pagina.

Il pulsante Guida widget apre la reference integrata del widget selezionato: elenca proprietà, tipi, valori predefiniti, capability ed esempi di stile. La reference completa è disponibile anche in Reference dei widget.

Caricare e usare un’immagine

1. Se il file è locale, usare Carica immagine nell’Explorer e scegliere un PNG, JPEG, GIF o WebP.
2. Per riusare un asset, aprire Immagini e filtrare il catalogo per nome o provenienza.
3. Selezionare Usa immagine oppure Copia e usa: l’editor propone un percorso sotto assets/ e valorizza il widget selezionato.
4. Compilare sempre alt, quindi scegliere adattamento (contain, cover, fill, none, scale-down) e posizione.
5. Verificare il risultato in Preview.

L’altezza impostata per il widget nella griglia determina anche lo spazio occupato dall’immagine. Per impostazione predefinita l’immagine viene contenuta senza deformazioni; il CSS scoped può modificarne object-fit tramite il selettore .portal-image.

Data Manager e query visuali

Dati apre il Data Manager del Portale. Non è necessario conoscere in anticipo la struttura della cartella data/:

1. creare una Data Resource e assegnare chiave e nome;
2. scegliere Connessione Environment oppure Modello Semantico;
3. per Environment caricare il catalogo, quindi scegliere schema, tabella, dimensioni, misure, aggregazioni e alias;
4. per un Modello Semantico scegliere la versione pubblicata del Progetto, quindi campi e misure governate;
5. impostare righe massime, timeout e parametri soltanto quando necessario;
6. salvare: il file data/<chiave>.resource.json viene creato e associato al widget selezionato.

Per Export dati, la stessa associazione può essere scelta in qualsiasi momento dalla tendina Data Resource dell’Inspector Visuale. La selezione aggiorna il binding del widget senza richiedere modifiche al JSON della pagina; togliendo la selezione viene rimosso il relativo binding. Modulo dati usa invece direttamente il Workflow configurato.

La modalità SQL custom avanzato è riservata a query read-only che non sono esprimibili dal configuratore. Richiede anche la dichiarazione delle colonne di output. Join, filtri o ordinamenti complessi possono essere rifiniti aprendo il JSON generato in modalità Codice.

Il browser non riceve le credenziali e non interroga direttamente la sorgente. Query, parametri, limiti e autorizzazioni vengono ricontrollati in esecuzione. Per le connessioni Oracle il selettore mostra gli schema accessibili all'utente della connessione, incluse le relative tabelle e viste. Se il catalogo non restituisce alcuno schema, il Data Manager lo segnala senza mostrare opzioni vuote.

Dati e integrazioni Sybot

Le risorse dati possono usare sorgenti e Modelli Semantici autorizzati. Le query sono in sola lettura e rispettano nuovamente i permessi dell’utente al momento dell’esecuzione.

Nel widget Modulo dati, il Workflow del Progetto è obbligatorio. Selezionandolo compare il mapping dei parametri: per ciascuno si può usare un campo del modulo, il valore predefinito del Workflow oppure un valore fisso non sensibile. Le corrispondenze con lo stesso nome vengono proposte automaticamente e restano modificabili.

I campi Lista valori disabilitano predefinito, minimo e massimo e possono essere associati soltanto a parametri Workflow Lista valori. L’Editor importa le opzioni definite nel Workflow, preserva etichette e valori e mostra nel Portale un menu a tendina. Per questi parametri non è disponibile il valore fisso: la scelta effettuata nel modulo viene verificata e passata direttamente al Workflow.

Quando il Workflow è configurato, il pulsante del modulo delega a esso la scrittura e non esegue direttamente append sulla Data Resource. Lo stato e le eventuali diagnostiche vengono aggiornati nel widget senza ricaricare la pagina.

Nel widget Vista Utente, scegliere dalla tendina una vista pubblicata del Progetto del Portale. La selezione registra automaticamente sia la vista sia la versione pubblicata pinned.

Nel widget Azione Workflow, scegliere un Workflow eseguibile del Progetto. Per ogni parametro indicare se usare il valore predefinito, chiedere il valore all’utente oppure salvare un valore fisso. I parametri sensibili possono essere solo richiesti a runtime; i Workflow con parametri file, non supportati, non sono selezionabili. In Preview l’avvio è reale: verificare gli effetti del Workflow sui sistemi collegati prima di usare il pulsante.

Scrivere un widget custom

La creazione e la modifica richiedono il ruolo Owner o Editor nel Progetto. I membri Viewer possono consultare il Portale in sola lettura.

Aggiungendo Widget custom sandbox, l’editor crea una cartella esplicita:

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

Apri codice componente passa a Codice e apre tutti e quattro i file. template.html contiene il markup, styles.css lo stile isolato, index.js esporta mount(sdk) e component.json dichiara file e capability. Il codice può modificare il DOM del proprio iframe, reagire agli eventi e usare PortalWidgetSDK per dati, navigazione interna e Workflow autorizzati. Non può accedere al documento padre, alla sessione, agli altri widget, a cookie o a rete diretta.

Nei file template.html, styles.css e index.js l’editor propone il completamento contestuale durante la digitazione; è possibile richiamarlo anche con Ctrl+Spazio o Cmd+Spazio. Scrivendo sdk. vengono mostrati soltanto i metodi consentiti dalle capability dichiarate nel component.json corrente. Il gutter segnala errori di sintassi JavaScript, identificatori non definiti, tag HTML non bilanciati e proprietà CSS non valide senza interrompere il salvataggio automatico.

In Guida widget → Widget custom sandbox → SDK Sandbox sono disponibili firma, parametri, valore restituito, capability richiesta ed esempio per ogni metodo: query, emit, navigate, runWorkflow/startWorkflow, workflowStatus, workflowLog, stopWorkflow, invalidateData, setContext, getContext e onDataInvalidated.

Dopo una mutazione, sdk.invalidateData() notifica le Data Resource cambiate; Tabelle e Grafici collegati si aggiornano in background senza ricaricare la pagina. sdk.onDataInvalidated() consente al Custom Widget di rifare la propria query. sdk.setContext() aggiorna il contesto condiviso e notifica tutti i consumatori; sdk.getContext() ne restituisce una copia locale. Le Data Resource basate su Modello Semantico vengono aggiornate anche quando la mutazione nasce da una risorsa diretta con una chiave differente.

Per consentire l’avvio dei Workflow, selezionare il widget e attivare Autorizza il widget al lancio dei Workflow nell’Inspector. L’editor aggiorna automaticamente il manifest: non occorre modificare component.json, aggiungere un binding alla pagina o conoscere in anticipo un singolo Workflow.

Le richieste dati simultanee dei diversi widget restano indipendenti e hanno un tempo massimo. Se il codice del widget non gestisce un errore durante l’avvio, il Portale termina comunque il caricamento e mostra un messaggio nel widget.

In Preview, sdk.runWorkflow(nomeOId, parametri) e il suo alias sdk.startWorkflow(nomeOId, parametri) avviano un’esecuzione reale sull’istanza Sybot corrente. Il Workflow deve appartenere al Progetto del Portale ed essere accessibile all’utente; se il nome non è univoco usare l’ID. Il widget può seguire l’esecuzione con sdk.workflowStatus() e sdk.workflowLog() e, se autorizzato, interromperla con sdk.stopWorkflow(). Considerare reali anche gli effetti sui sistemi collegati.

Per riutilizzare il widget, selezionarlo e usare Salva nel catalogo. Nel dialogo assegnare un nome descrittivo alla nuova versione. Ogni salvataggio crea una versione incrementale: le versioni esistenti non vengono sovrascritte.

La versione salvata è subito Disponibile nel catalogo dei widget custom del Progetto: usare Importa e aggiungi nel Portale desiderato. Non è richiesta alcuna conferma da parte di un altro utente.

Nell’Inspector del widget custom la voce Modalità di esecuzione consente di scegliere Sandbox o Trusted. Sandbox mantiene il codice isolato. Per Trusted, abilitare prima il codice trusted nelle Proprietà Portale, poi usare Salva nel catalogo: l’editor crea la versione firmata e la collega automaticamente al componente. Se il componente viene modificato, salvarlo di nuovo nel catalogo prima di validare o pubblicare.

Power BI e Qlik

Report Power BI supporta Secure URL, con sessione Microsoft del lettore, e App owns data, con profilo e binding governati dal Progetto. Dashboard Qlik supporta Secure URL e OAuth impersonation con qlik-embed. In entrambe le integrazioni i secret restano nella configurazione amministrativa e il widget salva soltanto URL o binding logici. Usare Diagnostica prima della Preview e verificare permessi, licenza e policy del provider sul dominio pubblicato.

La procedura completa è in Integrazioni governate.

Validare e provare la bozza

1. Salvare il file o applicare le proprietà dal composer.
2. Selezionare Valida.
3. Correggere gli elementi elencati nel pannello Problemi.
4. Selezionare Build per verificare la costruzione della bozza.
5. Selezionare Preview e provare layout, dati e interazioni.

La Preview è separata dalla versione pubblicata. Gli errori mostrano un messaggio utilizzabile e, quando disponibile, un identificativo da comunicare all’assistenza.

Per accessi e ciclo di pubblicazione consultare Pubblicazione e accessi.