PortalSettings V3

PortalSettings V3 ist ein providerbasiertes SPFx-WebPart für SharePoint Server Subscription Edition. Es wird einmal im Root Web einer Site Collection installiert und verwaltet die zentralen beziehungsweise lokalen Einstellungen erkannter Portal-Erweiterungen.

Version und Voraussetzungen

Eigenschaft	Wert
Version	3.2.7
SharePoint Framework	1.4.1
Build-Node	8.17.0
npm	6.x
Gulp	lokal 3.9.1
Komponente	Client-Side WebPart

Die Oberfläche wird vollständig vom WebPart erzeugt und verwendet kein innerHTML. Die moderne SitePages/PortalSettings.aspx wird bewusst per PnP-PowerShell provisioniert, damit das SPFx-WebPart auf SharePoint Server zuverlässig registriert bleibt.

Unterstützte Solutions

MegaMenu

• Erkennung der zentralen SPSite.UserCustomAction
• Auswahl des Navigationstermsets aus dem Default Site Collection Term Store
• Mega-Menu- oder Flyout-Modus
• Cache-Dauer und Cache-Version

Custom Branding

• sichere Header- und Footer-Elemente sowie Stylesheets
• deklarative GET-Suchformulare über die erlaubten Elementtypen form und input
• Prüfung von Formular-Action, Eingabetyp und Submit-Button vor dem Speichern
• Debug-Modus
• schemaerhaltendes Speichern unbekannter Properties

CurrentNavigation

• Auswahl des Navigationstermsets mit demselben Termset-Picker wie beim MegaMenu
• Cache-Dauer, Cache-Version und Debug-Modus
• maximale Navigationstiefe und optionale Anzeige des Root-Terms
• direkte Aktivierung als zentrale SPSite.UserCustomAction
• Hinweise zu CurrentNavigation.Root und CurrentNavigation.Hidden

CustomBranding

• zentrale SPSite.UserCustomAction
• Aktivierung der fehlenden Site-Collection-Action direkt aus PortalSettings
• versionierter portalSettings-Vertragsmarker mit Component-ID-Fallback
• Aktivierung und Debug-Modus
• CSS-Dateien inklusive media
• Allowlist externer CSS-Hosts
• Header- und Footer-Elemente
• Sicherheitsprüfung von Tags, Event-Attributen, URLs, Tiefe und Elementanzahl
• Kompatibilität mit dem Legacy-Root-Array elements

ExpiryIndicator

• Erkennung direkt nach der App-Installation über den Application Customizer im Root Web
• Site-Collection-Standard aus dem Root-Web-Property-Bag
• Übersicht registrierter Listen- und Bibliotheksbindungen
• Web-, Listen- und Datumsfeldauswahl ohne Eingabe technischer IDs
• Anbinden eines vorhandenen Datumsfeldes
• zentrale Laufzeiten, Farben und AND-/OR-Regeln
• lokale Ausnahmen pro Bindung
• Umschalten einer Bindung auf Vererbung
• Validierung von internen Feldnamen, Laufzeiten, Farbregeln und Bedingungsgruppen

Architektur

PortalSettingsWebPart
│
├── ProviderRegistry
│   ├── MegaMenuSettingsProvider
│   ├── CurrentNavigationSettingsProvider
│   ├── CustomBrandingSettingsProvider
│   └── ExpiryIndicatorSettingsProvider
│
├── DynamicFormRenderer
│   ├── Sections und Überschriften
│   ├── Hinweise und Trennlinien
│   ├── Text, Zahl, Toggle und Choice Cards
│   ├── Termset-Picker
│   ├── JSON- und Listen-Editoren
│   ├── Bindungsinventar
│   └── Zusammenfassung und JSON-Vorschau
│
└── Storage
    ├── SPSite.UserCustomActions
    ├── Root-Web-Property-Bag
    └── Field.ClientSideComponentProperties

Provider beschreiben fachliche Felder und Layout deklarativ. Der Renderer kennt keine MegaMenu-, Branding- oder ExpiryIndicator-Sonderformulare. Neue Standardfelder benötigen deshalb keine Änderung am Renderer.

Spezielle Infrastruktur wie Taxonomy oder Field-Customizer-Bindungen wird über geprüfte Services angebunden. Provider dürfen kein freies HTML, JavaScript oder CSS liefern.

Layout-Elemente

Ein Provider kann folgende Elementtypen verwenden:

• heading, text, notice, divider, group
• textField, number, boolean
• choice, choiceCards
• termSet, stringList, json
• bindingInventory
• propertySummary, jsonPreview

Sections unterstützen ein-, zwei- und dreispaltige Layouts, optionale Beschreibungstexte sowie einklappbare Expertenbereiche. Elemente können über visibleWhen abhängig von anderen Konfigurationswerten erscheinen.

Das Styling verwendet ausschließlich SharePoint-Themeslots wie themePrimary, neutralPrimary, neutralLight und white. Responsive Layout, Tastaturfokus, Forced Colors und reduzierte Bewegung sind berücksichtigt.

Provider-Vertrag

Ein Provider implementiert:

interface ISettingsProvider<TConfig> {
  key: string;
  displayName: string;
  description: string;
  schemaVersion: number;
  minimumPortalSettingsVersion: string;
  componentIds: string[];
  storage: IProviderStorageDefinition;
  sections: ISettingsSection[];

  createDefault(): TConfig;
  normalize(value: any): TConfig;
  validate(value: TConfig): string[];
}

Neue Provider werden unter src/providers angelegt und einmal in ProviderRegistry.ts registriert. Ein Provider definiert selbst:

• Erkennungs-IDs
• Speicherart
• Konfigurationsversion
• Sections und Layout
• Felder und Hilfetexte
• Normalisierung
• Validierung
• Standardwerte

Schutz vor Datenverlust

PortalSettings normalisiert gelesene Werte für die Anzeige, überschreibt beim Speichern aber nicht blind das komplette Objekt. Bearbeitete Werte werden rekursiv in die ursprüngliche Konfiguration gemergt. Unbekannte zukünftige Properties bleiben dadurch erhalten.

JSON-Editoren ändern das Modell nur, wenn der aktuelle Inhalt gültiges JSON ist. Unsichere CustomBranding-Strukturen und ungültige ExpiryIndicator-Regeln werden vor dem Speichern abgelehnt.

Berechtigungen

Das WebPart zeigt die Verwaltungsoberfläche nur Site-Collection-Administratoren. Die eigentliche Sicherheitsgrenze bleiben die SharePoint-Berechtigungen der REST-Endpunkte.

Für ExpiryIndicator-Bindungen werden zusätzlich Berechtigungen zum Verwalten der betreffenden Liste und Felder benötigt.

Build

npm install
npm test
npm run package

Das Paket entsteht unter:

sharepoint/solution/portal-settings.sppkg

npm run package führt die Provider- und statischen Sicherheitsprüfungen vor dem Ship-Build aus.

Installation

1. portal-settings.sppkg im App Catalog durch Version 3.2.7.0 ersetzen.
2. Die App im Root Web der gewünschten Site Collection installieren oder aktualisieren.
3. Die Seite mit dem PnP-PowerShell-Skript erzeugen beziehungsweise reparieren:

.\deployment\Add-PortalSettingsPage.ps1 `
  -SiteUrl 'http://clshp001/sites/target' `
  -Publish

Das Skript verwendet standardmäßig PortalSettings.aspx und platziert dort das Portal-Settings-WebPart.

Migration von V2

V3 liest die vorhandenen Konfigurationsorte direkt weiter:

• MegaMenu und CustomBranding aus zentralen UserCustomActions
• ExpiryIndicator-Defaults, Descriptor und Bindungsinventar aus dem Root Web
• lokale ExpiryIndicator-Ausnahmen aus dem gebundenen Feld

Es ist keine Datenmigration in eine neue Liste erforderlich. Empfohlenes Vorgehen:

1. Paket aktualisieren und die App im Root-Web aktualisieren.
2. Das PnP-Skript ausführen, wenn PortalSettings.aspx fehlt oder das WebPart noch nicht enthält.
3. Alle Provider laden, Konfigurationen testweise speichern und Root Web sowie Subwebs prüfen.

Diagnose

Wenn kein Tab erscheint, muss zunächst die zentrale Registrierung der jeweiligen Solution vorhanden sein. PortalSettings erkennt keine bloß im App Catalog hochgeladene, aber nicht für die Site Collection registrierte Runtime.

Browserkonsole:

performance.getEntriesByType('resource')
  .map(function (entry) { return entry.name; })
  .filter(function (url) { return url.toLowerCase().indexOf('portal-settings') >= 0; });

Die sichtbare Statusmeldung enthält REST-Statuscode und SharePoint-Fehlertext, wenn Lesen oder Speichern fehlschlägt.