CustomBranding/ToDo.md

CustomBranding – Umsetzungsstand

Analysestand: 20.07.2026
Umgesetzt: 20.07.2026
Ausgangsversion: 1.0.4
Zielversion: 3.0.5 Status: Implementierung und lokale Qualitätssicherung abgeschlossen

Zielbild

CustomBranding wird pro Site Collection genau einmal über eine SPSite.UserCustomAction registriert und konfiguriert. Moderne und klassische Seiten lesen dieselben versionierten ClientSideComponentProperties. Es werden weder eine versteckte Liste noch ein Property Bag eingesetzt. PortalSettings 3.0.1 kann die zentrale Action erkennen, bearbeiten und bei Bedarf beim ersten Speichern anlegen.

Sicherheit und Konfigurationsmodell

• Stringbasiertes HTML und innerHTML durch einen DOM-Renderer ersetzt.
• Laufzeit-Whitelist für Elementtypen umgesetzt.
• Globale und elementspezifische Attribut-Allowlisten umgesetzt.
• Alle Ereignisattribute on* gesperrt.
• Relative URLs, HTTP/HTTPS und mailto kontrolliert; javascript: und data: gesperrt.
• target="_blank" automatisch mit noopener noreferrer abgesichert.
• Style-Property-Allowlist und Prüfung gefährlicher CSS-Werte umgesetzt.
• Externe Stylesheets nur per HTTPS und expliziter Host-Allowlist ermöglicht.
• Limits für Konfigurationsgröße, Rekursion, Elemente und Stylesheets umgesetzt.
• Versioniertes Schema 2 eingeführt.
• Bestehende 1.x-Konfigurationen mit Root-Property elements weiter unterstützt.
• enabled, debug, allowedCssHosts, cssfiles, Top und Bottom konsistent typisiert.
• Unbekannte Properties werden ignoriert; Warnungen erscheinen nur im Debug-Modus.
• Den bisherigen Portal-Settings-Link als sicheren Standard-Footer in der Runtime verankert.
• Versionierten, rein deklarativen PortalSettings-Vertragsmarker ergänzt.
• Runtime, Standardkonfiguration und Deployment-Skript auf denselben Providervertrag gebracht.
• Direkte Aktivierung aus PortalSettings 3.0.1 dokumentiert.

Lifecycle und Stylesheet-Management

• Top- und Bottom-Placeholder werden unabhängig angefordert und gerendert.
• Nach dem Dispose eines einzelnen Placeholders kann dieser später erneut erworben werden.
• changedEvent wird beim Extension-Dispose deregistriert.
• Dispose ist idempotent und setzt alle eigenen Referenzen zurück.
• Eigene Hosts werden entfernt, fremde Knoten bleiben erhalten.
• CSS-URLs werden absolut normalisiert und instanzübergreifend dedupliziert.
• Reihenfolge und optionale media-Angabe bleiben erhalten.
• Ladefehler und Timeouts werden debug-gesteuert protokolliert.
• Fremde vorhandene Stylesheets werden wiederverwendet und nie entfernt.
• Nur Stylesheets der letzten eigenen Referenz werden beim Dispose entfernt.

Barrierefreiheit und Mehrsprachigkeit

• Bilder ohne alt werden verworfen; dekorative Bilder mit leerem alt sind möglich.
• Buttons erhalten immer type="button"; leere Links und Buttons werden verworfen.
• ARIA-Attribute sind auf eine feste Allowlist begrenzt.
• Fehlermeldungen verwenden role="status".
• Deutsches und englisches Localized Resource Bundle ergänzt und verwendet.
• Debug-gesteuerter Logger mit einheitlichem Präfix umgesetzt.
• Beispiel-CSS mit sichtbaren Fokuszuständen, responsivem Layout und Forced-Colors-Regel ergänzt.
• Tastaturbedienung, 200-Prozent-Zoom und Windows-Hochkontrast in der Zielumgebung manuell abnehmen.

Bereitstellung und Scope

• Paket auf skipFeatureDeployment und zentrale SPSite.UserCustomAction umgestellt.
• Alte web-scoped Feature-Registrierung und sharepoint/assets/elements.xml entfernt.
• Nicht verwendete Azure-Storage-Konfiguration entfernt.
• SharePoint-SE-Deploymentskript verwendet zuerst das PowerShell-Modul und nur als Fallback das Snap-in.
• Doppelte Site- und alte Web-Actions werden idempotent bereinigt.
• Vorhandene Properties bleiben standardmäßig erhalten.
• Bewusste Optionen für Reset, Debug, Disable und externe CSS-Hosts ergänzt.
• Root Web, vorhandenes Subweb und anschließend neu angelegtes Subweb auf dem Zielserver abnehmen.

MegaMenu-Integration

• CustomBranding mit Sequence 90 vor MegaMenu (100) und Current Navigation (110) registriert.
• Top-Branding direkt als Geschwister von CustomNavigation in CustomHeader integriert; Bottom-Host bleibt separat.
• Renderer verändert ausschließlich eigene, per Ownership-Attribut markierte Top-Knoten und Bottom-Host-Inhalte.
• Wiederholtes Rendern löscht CustomNavigation oder fremde DOM-Knoten nicht.
• Gemeinsamer Betrieb und Ownership in der README dokumentiert.
• Beide realen Lade-Reihenfolgen mit installiertem MegaMenu auf dem Zielserver abnehmen.

Classic SharePoint

• Classic-Unterstützung als fachliches Ziel bestätigt.
• Separate ES5-Runtime ohne SPFx-Abhängigkeit erstellt.
• Classic-Runtime verwendet dasselbe zentrale Schema und dieselben Sicherheitsgrenzen.
• Automatischer Classic-Build über npm run build:classic umgesetzt.
• Optionaler site-scoped ScriptLink im Deploymentskript ergänzt.
• Bereitstellung, Entfernung und Browserdiagnose dokumentiert.
• Classic-Listen-, Bibliotheks- und Publishing-Seite auf dem Zielserver visuell abnehmen.

Projektbereinigung und Dokumentation

• Node-Engine auf >=6.9.0 <9.0.0 gesetzt und Node.js 8.17.0 dokumentiert.
• Package und Solution konsistent auf Version 3.0.0 angehoben.
• Nicht verwendete Abhängigkeit @microsoft/sp-dialog entfernt.
• Localized Resources aktiviert und ergänzt.
• serve.json auf das echte, sichere Schema korrigiert.
• Nicht verwendete Dateien entfernt.
• README mit Architektur, Schema, Sicherheitsgrenzen, Deployment, Classic, Upgrade und Diagnose neu erstellt.
• Sichere JSON- und CSS-Beispiele ergänzt.

Automatisierte Qualitätssicherung

• Testbare Module für Normalisierung, URLs, Attribute, Styles, DOM und CSS-Loading ausgelagert.
• Positivtests für alle erlaubten Elementtypen ergänzt.
• Negativtests für Tags, Event-Attribute, URLs, Styles und fehlendes alt ergänzt.
• Tests für Legacy-Schema, Schema 2, Tiefen- und Größenlimit ergänzt.
• DOM-Test für sichere Elementerzeugung und Cleanup ergänzt.
• CSS-Tests für Deduplizierung, Reihenfolge, Referenzen und fremde Stylesheets ergänzt.
• Statische Prüfungen für JSON, Konfiguration, Lifecycle-Regeln, Classic-JavaScript und PowerShell ergänzt.
• npm test als zwingendes Gate vor npm run package eingebaut.
• Classic-Build als Teil der Paketierung automatisiert.
• Ship-Build mit Node.js 8.17.0 als abschließender Zielserver-Schritt dokumentiert.

Lokale Prüfergebnisse

• Hauptprojekt kompiliert mit TypeScript ohne Ausgabe.
• npm test: 32 Config-, 6 DOM-, 8 CSS- und 20 statische Prüfungen erfolgreich.
• PowerShell-Syntax für Deployment und Classic-Build erfolgreich geprüft.
• Classic-Build erzeugt beide Distributionsdateien erfolgreich.

Noch offene Abnahme auf SharePoint SE

1. Ship-Paket mit Node.js 8.17.0 bauen und im App Catalog aktualisieren.
2. Zentrale Registrierung mit deployment/add-custombranding.ps1 herstellen.
3. Moderne Seiten in Root Web, bestehendem und neuem Subweb prüfen.
4. MegaMenu-Ladereihenfolgen sowie Tastatur, Zoom und Hochkontrast prüfen.
5. Optional Classic-Runtime bereitstellen und klassische Seitentypen prüfen.