PortalSettings/README.md

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.0.0
SharePoint Framework	1.4.1
Build-Node	8.17.0
npm	6.x
Gulp	lokal 3.9.1
Komponente	Client-Side WebPart

Die frühere provisionierte PortalSettings.aspx und der leere Application Customizer wurden entfernt. Die Oberfläche wird vollständig vom WebPart erzeugt und verwendet kein innerHTML.

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
• Debug-Modus
• schemaerhaltendes Speichern unbekannter Properties

CustomBranding

• zentrale SPSite.UserCustomAction
• 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

• 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
│   ├── 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.0.0.0 ersetzen.
2. Die App im Root Web der gewünschten Site Collection installieren oder aktualisieren.
3. Eine moderne Seite erstellen.
4. Das WebPart Portal Settings einmal auf der Seite hinzufügen.
5. Die Seite veröffentlichen und nur für die gewünschte Administratorgruppe verlinken.

Optional kann eine Seite per PnP PowerShell erzeugt werden:

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

Die Standardseite heißt absichtlich PortalSettingsV3.aspx, damit die alte V2-Seite während der Abnahme erhalten bleiben kann.

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. V3-Paket installieren.
2. PortalSettingsV3.aspx parallel zur alten Seite bereitstellen.
3. Alle drei Provider laden und Konfigurationen testweise speichern.
4. Root Web und Subwebs prüfen.
5. Erst danach die alte PortalSettings.aspx löschen oder archivieren.

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.