Passa al contenuto principale
Versione: 2.0

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.

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.

Explorer e Problemi possono essere collassati con il pulsante nella loro intestazione. Nell’Explorer, il chevron accanto a ogni directory permette inoltre 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.

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. È possibile aggiungere un widget, selezionarlo e configurare:

  • titolo e proprietà;
  • posizione, larghezza e altezza nella griglia;
  • stili per la singola istanza;
  • CSS scoped;
  • resa Desktop, Tablet e Mobile.

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

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.

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.

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.

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.

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 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. Nella Preview viene eseguita soltanto la verifica della configurazione.

Scrivere un widget custom​

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.

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.