Widget-Referenz der Portale

Diese Seite beschreibt die im Initialkatalog enthaltenen Widgets. Core-Widgets verfügen über visuelle Steuerelemente und gegebenenfalls erweiterte JSON-Eigenschaften; native Benutzeransicht-Typen werden vollständig über geführte Steuerelemente konfiguriert.

Gemeinsame Eigenschaften

Eigenschaft	Typ	Verwendung
title	String	Optionaler Titel des Widgets.
hidden	Boolean	Versteckt das Widget, wenn auf true gesetzt.
placement.x, placement.y	Integer	Position im Raster, beginnend bei 1.
placement.w, placement.h	Integer	Breite und Höhe in Zellen.
style	Objekt	CSS-Eigenschaften, Zustände und Breakpoints der Instanz.
style.rawCss	String	Fortgeschrittene, scope-basierte CSS-Regeln.

Im Inspector sind das Feld Titel und die JSON-Eigenschaft title in beide Richtungen synchronisiert. Eine in einem der beiden eingegebene Zeichenfolge wird auch im anderen angezeigt. Um die Überschrift zu entfernen, entfernen Sie title aus dem JSON oder lassen Sie Titel leer; das gesteuerte Speichern speichert die Änderung automatisch.

Die gesteuerten Steuerelemente werden automatisch gespeichert und zeigen ein Bestätigungstaster an. Für JSON-Eigenschaften, JSON-Stil und scope-basiertes CSS verwenden Sie stattdessen Änderungen fortgeschritten speichern.

Abschnitt (layout.section)

Gruppiert verwandte Inhalte. title steuert die sichtbare Überschrift. Es ist auch als Zielstruktur für benutzerdefinierte Komponenten nützlich.

Text (content.text)

Die Eigenschaft text enthält den einfachen Text; Zeilenumbrüche werden beibehalten.

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

Um nur den Inhalt zu ändern, verwenden Sie .portal-text im scope-basierten CSS.

Hero (content.hero)

Einleitungsblock mit eyebrow, title, subtitle, Bild (assetPath) und optionalem Button (buttonLabel, routeId). routeId akzeptiert nur eine interne Route. Verwenden Sie pro Seite nur einen einzigen Haupt-Hero und füllen Sie imageAlt aus, wenn ein Bild vorhanden ist. Bildlayout verwendet das Bild als Hintergrund oder platziert es oben, mittig oder unten, ohne es zu verzerren.

Karte (content.card)

Kombiniert title, text, Bild und interne Verknüpfung. In Rastern sollten einheitliche Abmessungen verwendet werden; Bildlayout verwendet das Bild als Kartenhintergrund oder platziert es oben, mittig oder unten und erhält dabei seine Proportionen.

Trennlinie (content.divider)

orientation kann horizontal oder vertical sein; title ist ein optionales Label. Eine vertikale Trennlinie erfordert eine angemessene Rasterhöhe.

Verknüpfung (navigation.link)

• label: Button-Label;
• routeId: Identifikator einer internen Route, die in portal.json deklariert ist.

Das Widget öffnet keine externen URLs.

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

Menü (navigation.menu)

items ist ein Array von {label, routeId}, das aus den bestehenden Routen ausgewählt wird. orientation kann horizontal oder vertical sein; collapseOnMobile aktiviert den kompakten Modus auf kleinen Bildschirmen.

Navigationsreiter (navigation.tabs)

Zeigt verwandte Routen als Reiter an. items behält die Reihenfolge bei, während stretch die Reiter über die verfügbare Breite verteilt. Auf Mobilgeräten scrollen die Reiter horizontal.

Breadcrumb (navigation.breadcrumb)

items beschreibt den hierarchischen Pfad; der letzte Eintrag kann routeId nicht haben. separator akzeptiert einen kurzen Text. Der Breadcrumb ersetzt nicht das Hauptmenü.

Bild (media.image)

• assetPath: Pfad zum Bild im Repository;
• alt: barrierefreie Alternativbeschreibung.

Laden Sie zuerst die Datei aus dem Explorer und verwenden Sie dann denselben Pfad:

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

Es können PNG, JPEG, GIF und WebP bis zum vom Editor angegebenen Limit hochgeladen werden. Die Höhe placement.h dimensioniert auch das Bild, das den gesamten verfügbaren Raum nutzt, ohne verzerrt zu werden. Um den Ausschnitt zu ändern, verwenden Sie beispielsweise .portal-image { object-fit: cover; } im scope-basierten CSS.

Nur-Lese-Modul (form.readonly)

fields ist ein Array von Objekten mit key, label und value:

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

Einziehbares Panel (layout.collapsible)

title ist immer sichtbar, content enthält den Text und openByDefault wählt den Anfangszustand aus. Verstecke keine Fehler oder erforderlichen Bestätigungen in einem geschlossenen Panel.

Seitenleiste (layout.sidebar)

Seitenbereich, der im Widget eingegrenzt ist. side ist left oder right; collapsible und collapsedByDefault steuern die kompakte Steuerung. Für eine vollständige Navigation wird ein vertikales Menü bevorzugt.

Schublade (layout.drawer)

Überlagerungspanel geöffnet über buttonLabel. side wählt die Seite aus und closeOnScrim aktiviert das Schließen im Hintergrund. Der Runtime verwaltet Escape und Fokusrückgabe; verwenden Sie das Drawer nicht für blockierende Nachrichten.

Datentabelle (data.table)

• columns: sortierte Liste der anzuzeigenden Schlüssel;
• bindings.data.resourceKey: In der Data Resource-Ordner data deklariert.

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

Die Data Resource kann autorisierte Objekte, Datenquellen oder semantische Modelle abfragen. Der Browser greift nicht direkt auf die Quelle zu.

Der Befehl Daten erstellt und bearbeitet die Ressource mit visueller Auswahl von Verbindung, Schema, Tabelle, Dimensionen, Metriken und Aggregationen oder eines veröffentlichten semantischen Modells, Feldern und Metriken. JSON öffnen ermöglicht nach dem ersten Speichern fortgeschrittene Konfigurationen.

Datenformular (form.write)

Erfasst typisierte Felder und startet einen autorisierten Workflow. Felder definieren öffnet einen eigenen Dialog für Schlüssel, Bezeichnung, Typ, Standardwert, Pflichtfeld, Minimum und Maximum; mindestens ein Feld ist erforderlich, Grenzwerte sind nur für Zahlen, Datums- und Datums-/Zeitwerte aktiv. Der Workflow ist obligatorisch, und die Liste enthält nur ausführbare Projekt-Workflows mit Eingabedaten. Workflow-Standardwerte und feste Werte müssen einem Formularfeld zugeordnet werden; in der Vorschau überschreiben sie dessen Standardwert und erscheinen direkt im deaktivierten Eingabefeld, ohne zusätzliche Textzeile. Das Datenformular benötigt keine Data Resource, daher erscheint dieser Abschnitt nicht im Inspector; beim Bearbeiten einer älteren Konfiguration wird eine veraltete Datenbindung automatisch entfernt.

Der Typ Werteliste verwendet die im Workflow konfigurierten Optionen und wird als Dropdown-Menü dargestellt. Er besitzt weder Standardwert noch Minimum oder Maximum, erlaubt keinen festen Wert und kann nur einem Workflow-Parameter desselben Typs zugeordnet werden. Bezeichnungen und Werte bleiben getrennt, und die Auswahl wird vor der Ausführung validiert.

Balkendiagramm (data.chart)

Zeigt serverseitig berechnete Kennzahlen als zugängliche horizontale Balken. series enthält Schlüssel, Beschriftung und optionale Farbe jeder Kennzahl; das Binding muss auf eine aggregierte Data Resource verweisen.

Datei hochladen (form.upload)

Leser können ein Dokument in den Upload-Bereich ziehen oder auf ihrem Gerät auswählen. Das Widget aktualisiert seinen Status ohne Neuladen der Seite und zeigt anschließend Dateiname, Größe und die Aktion zum Entfernen. Die Schaltfläche Herunterladen ist nur verfügbar, wenn sie im Inspector aktiviert wurde.

Die Konfiguration erlaubt PDF, PNG, JPG/JPEG, DOCX, TXT, CSV und XLSX, eine maximale Größe von 1 bis 256 MB sowie Datei auf dem Server verschlüsseln. Sybot prüft vor dem Speichern den tatsächlichen Inhalt und weist getarnte ausführbare Dateien, Skripte und nicht zur Erweiterung passende Dateien ab. Jeder Leser kann nur selbst hochgeladene Dateien herunterladen oder entfernen.

Datenexport (data.export)

Über die Kontrollkästchen im Inspector können CSV, XLSX oder beide Formate angeboten werden; mindestens ein Format muss ausgewählt bleiben. In der Data Resource muss kein Exportbefehl aktiviert sein: Abfragbare Verbindungen, semantische Modelle und Working Datasets werden unterstützt. Widget-Binding, Portalzugriff und Berechtigungen für die Quelle werden weiterhin geprüft. Die erzeugte Datei ist temporär und neutralisiert für Tabellenkalkulationen potenziell gefährliche Werte.

Benutzeransicht (user-view.embed)

• viewId: Benutzeransicht-ID;
• versionId: Version ID der zu blockierenden veröffentlichten Release.

Beide Werte sind obligatorisch. Im visuellen Modus zeigt die Leiste nur die veröffentlichten Benutzeransichten des Projekts des Portals an und füllt beide IDs automatisch aus. Die Versions-PIN verhindert, dass eine spätere Änderung der Ansicht eine bereits genehmigte Portal-Release verändert.

In der Vorschau und im veröffentlichten Portal wird die Ansicht direkt im Widget angezeigt, ohne dass ein zweiter Zugriff erforderlich ist. Wenn die Sitzung oder die Berechtigungen nicht mehr gültig sind, zeigt das Widget eine Diagnosestelle anstelle der Ansicht.

Im Portal nimmt der erweiterte Header der Ansicht keinen Platz ein: Aktualisierung, Filter und Darstellung sind in einer schwebenden Symbolleiste zusammengefasst.

Widget Benutzeransicht (user-view.widget)

Incorpora nur einen Standard- oder benutzerdefinierten Widget einer veröffentlichten Ansicht. Die Palette und der Inspector zeigen ausschließlich Widgets von Ansichten an, die im Projekt verfügbar sind, und registrieren viewId, versionId und widgetKey. Diagramme, KPIs, Tabellen, Karten sowie Widgets aus dem benutzerdefinierten Katalog der Ansichten werden ebenfalls unterstützt.

Der Runtime lädt nur den für das ausgewählte Widget erforderlichen Teil der View und die Datenquelle; es ist nicht möglich, widgetKey zu ändern, um auf eine andere Datenquelle zuzugreifen.

Mit Benutzeransichten gemeinsam genutzte native Typen

Das Portal kann neue Instanzen aller im Editor der Benutzeransichten verfügbaren Typen erstellen. Die Palette zeigt den Typ und nicht die bereits in einzelnen Ansichten konfigurierten Instanzen. Neue Instanzen gehören zum Portal und verwenden die gemeinsamen Eigenschaften, Hilfetexte und Renderer.

Verfügbar sind Diagramme, Karten, KPIs, Datensatzdetails, Inhalte, Layouts, Navigations- und Filtersteuerungen, Workflow-Aktionen, Diagnose und Datentabelle. Datentypen benötigen eine Data Resource des Portals; Typen, die einen Workflow starten, benötigen die entsprechende Bindung.

Der Inspector gruppiert Eigenschaften in Abschnitte und bietet visuelle Steuerelemente für Spalten, verknüpfte Widgets, Schwellenwerte, Zeiträume und Zuordnungen; JSON muss nicht bearbeitet werden. Die Abschnitte behalten ihren geöffneten oder geschlossenen Zustand während der automatischen Speicherung bei. Typen mit demselben Namen wie ein Core-Widget des Portals bleiben getrennt: Der native Benutzeransicht-Eintrag ersetzt oder verändert die Core-Implementierung nicht.

Workflow-Aktion (workflow.action)

• workflowId: zugeordneter Workflow;
• buttonLabel: Text des Buttons;
• confirmationText: optionale Bestätigung;
• fields: gesammelte Parameter vor dem Start;
• bindings.workflow.workflowId: muss props.workflowId entsprechen.

In Visual Mode zeigt der Tabulator nur die ausführbaren Workflows des Portalprojekts an. Für jeden Parameter generiert der Inspector eine Auswahl zwischen dem Standardwert (default), der vom Benutzer angefordert wird (prompt) und einem festen Wert (literal). Sensible Parameter erlauben keine festen Werte; Workflows mit Dateiparametern sind nicht auswählbar.

In der Vorschau führt die Aktion einen Dry-Run aus. Im aktiven Portal wird der Workflow nur gestartet, wenn Benutzer, Portal und Release autorisiert sind.

BPMN-Diagramm (bpmn.viewer)

• templateId: BPMN-Objekt des Projekts;
• versionId: bereitgestellte und festgelegte Version.

Die Auswahlliste setzt beide Werte und zeigt nur zugängliche Diagramme. Vorschau und Runtime verwenden einen Read-only-Viewer und prüfen die Leserrechte erneut.

Bericht Power BI (bi.powerbi)

Das Widget unterstützt Secure URL mit der Microsoft-Sitzung des Betrachters und App owns data mit einem projektverwalteten Profil und einer Bindung. Publish to web-URLs sowie Werte mit Token oder Anmeldedaten werden abgelehnt. Die vollständige Konfiguration beider Modi finden Sie unter Power BI: Secure URL und App owns data.

Dashboard Qlik (bi.qlik)

• embedMode: secure_url oder oauth_impersonation;
• embedUrl: Qlik-HTTPS-URL, nur für Secure URL;
• bindingKey: logische Projektbindung, nur für OAuth impersonation;
• allowFullscreen: aktiviert den Vollbildmodus.

Der verwaltete Modus speichert App ID und Inhaltstyp in der Bindung und nutzt ein von Sybot erzeugtes kurzlebiges Token. Profil und Endpunkt müssen die Diagnose bestehen; die Release behält die Bindungsrevision. Siehe Verwaltete Integrationen.

Custom-Sandbox-Widget (custom.sandbox)

Eine Custom-Komponente verwendet diese Struktur:

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

component.json deklariert Dateien und Fähigkeiten:

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

JavaScript kann den DOM innerhalb seines eigenen Iframes ändern. Für Daten und Aktionen wird PortalWidgetSDK verwendet; direkte Netzwerkkalls, Zugriff auf das übergeordnete Dokument, Cookies und Session-Storage sind nicht erlaubt.

Der Inspector bietet Komponenten-Code öffnen an, der automatisch zu Code wechselt und Manifest, Template, CSS und JavaScript öffnet. Der Projektkatalog kann auch eine Komponente von einem anderen Portal kopieren; die Komponente wird zu einer versionierbaren Kopie im aktuellen Repository.

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

Für Live-Aktualisierungen registrieren Sie sdk.onDataInvalidated(listener) und wiederholen die Abfrage, wenn das Ereignis die vom Widget verwendete Ressource enthält. Rufen Sie nach einer Mutation sdk.invalidateData(resourceKey) auf. setContext() und getContext() verwalten den gemeinsamen Kontext ohne Zugriff auf das übergeordnete Dokument.

Aktivieren Sie im Inspector Dem Widget das Starten von Workflows erlauben, um die Capability workflow:start ohne JSON-Bearbeitung zu verwalten. Für ein Custom-Widget ist kein Eintrag bindings.workflow erforderlich. Mit sdk.runWorkflow(nameOderId, parameter) oder dem Alias sdk.startWorkflow() kann jeder ausführbare Workflow des aktuellen Projekts gestartet werden; Projektgrenze und Benutzerberechtigungen werden weiterhin zur Laufzeit geprüft.

Stil, Zustände und Breakpoints

CSS-Eigenschaften verwenden kebab-case-Namen. Die Bereiche states und breakpoints wenden lokale Variationen an:

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

Unterstützte Zustände sind hover, focus, active und disabled; Breakpoints sind sm, md, lg und xl. Desktop, Tablet, Mobile und Preview sollten immer überprüft werden.

Power BI: Secure URL und App owns data

Das Widget bi.powerbi bietet zwei Modi:

• Secure URL verwendet einen reportEmbed-Link und die Microsoft-Sitzung des Betrachters. Wenn der Betrachter noch nicht angemeldet ist, wird erwartungsgemäß die Anmeldeseite angezeigt.
• App owns data verwendet eine Power-BI-Bindung des Projekts. Sybot bezieht serverseitig ein kurzlebiges Token; Anmeldedaten und Token werden nie im Widget gespeichert.

Für App owns data erstellt ein Super Admin zunächst das Secret auf der Registerkarte Credential Vault im Control Center. Danach öffnet der Projekteigentümer Profile und Berichte verwalten im Portal Editor und erstellt ein Profil, eine Bindung und mindestens den Authoring-Endpunkt. Die Auswahllisten laden die für das Profil verfügbaren Arbeitsbereiche und Berichte. Führen Sie vor der Vorschau die Diagnose aus.

Jedes Projekt kann mehrere Profile verwenden, auch für unterschiedliche Power-BI-Tenants oder -Benutzer, und für jeden Endpunkt ein Profil auswählen. Microsoft Public Cloud, US Government GCC und Power BI China sind verfügbar. Der Vault unterstützt Installations- oder Projektumfang, Ablaufdatum, Rotation, Deaktivierung und endgültigen Widerruf. RLS wird mit einer Sybot-Identität, einem statischen Wert und Rollen konfiguriert; erweiterte SDK-Einstellungen bleiben optional.

Eigenschaft	Verwendung
embedMode	secure_url oder app_owns_data.
embedUrl	reportEmbed-URL, nur für Secure URL.
reportBindingKey	Logische Projektbindung, nur für App owns data.
variantKey	Endpunktvariante, normalerweise default.
pageName	Optionale Startseite.
showFilters	Blendet den Filterbereich ein oder aus.
showPageNavigation	Blendet die Seitennavigation ein oder aus.

Eine Bindung kann für Authoring, Development, Staging, Production oder ein bestimmtes Ziel unterschiedliche Berichte und Identitäten auflösen. Die Rotation eines Vault-Secrets erfordert keine Änderung am Widget. Das Einbettungstoken wird vor Ablauf automatisch erneuert.

Vor dem Deployment muss jede App-owns-data-Bindung und -Variante der Release einen diagnostizierten Endpunkt für das Ziel oder den Fallback seiner Umgebung besitzen. Fehlt er, blockiert der Preflight das Deployment und nennt die zu korrigierende Konfiguration; Secure URL benötigt diese Prüfung nicht.