Widget-Referenz der Portale

Diese Seite beschreibt die im Initialkatalog enthaltenen Widgets. Die Eigenschaften werden im Inspector als JSON-Objekt geändert; Titel, Geometrie und der gemeinsame Stil verfügen zudem über visuelle Steuerelemente.

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.

Karte (content.card)

Kombiniert title, text, Bild und interne Verknüpfung. In Rastern sollten einheitliche Abmessungen verwendet werden; .portal-card__media ermöglicht die Einstellung des Seitenverhältnisses und object-fit.

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 speichert sie in einem verknüpften Working Dataset. Das Binding muss das Hinzufügen von Datensätzen erlauben; die Validierung wird auf dem Server wiederholt und der Browser greift nie direkt auf den Speicher zu. Nach erfolgreichem Speichern werden verknüpfte Tabellen und Diagramme ohne Neuladen aktualisiert.

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.

Datenexport (data.export)

Bietet CSV und XLSX nur an, wenn die Data Resource den Export erlaubt. Die erzeugte Datei ist temporär, berücksichtigt die Berechtigungen des Lesers 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.

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;
}

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.