SPFx-Projekte/CustomBranding
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
dev-3.0
CustomBranding/ToDo.md
Torsten Brendgen 490e9adbd8 feat: Add custom branding functionality with CSS and JSON configuration 
- Introduced custom branding CSS styles in `custom-branding.css`.
- Created example JSON configuration for custom branding in `custom-branding.example.json`.
- Implemented branding configuration logic in `BrandingConfig.ts` to normalize and validate branding settings.
- Developed CSS loader to manage loading and unloading of custom stylesheets in `BrandingCssLoader.ts`.
- Added DOM rendering capabilities for branding elements in `BrandingDomRenderer.ts`.
- Defined types and interfaces for branding elements and configurations in `BrandingTypes.ts`.
- Included localization support for German in `de-de.js`.
- Added unit tests for branding configuration, CSS loader, and DOM renderer.
- Validated project structure and static assets with new validation scripts.
2026-07-20 22:55:47 +02:00

7.0 KiB
Raw Permalink Blame History

CustomBranding – Umsetzungsstand

Analysestand: 20.07.2026
Umgesetzt: 20.07.2026
Ausgangsversion: 1.0.4
Zielversion: 3.0.0
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 bleibt in diesem Durchlauf unverändert; der Vertrag für das spätere PortalSettings-v3-Webpart ist in der README dokumentiert.

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.
  • Keine feste Abhängigkeit oder Verlinkung zu PortalSettings mehr vorhanden.

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

  • Stabile Hosts CustomHeader, CustomBrandingTopHost, MegaMenuHost, CustomFooter und CustomBrandingBottomHost definiert.
  • Renderer verändert ausschließlich eigene Host-Inhalte.
  • Wiederholtes Rendern löscht den MegaMenuHost 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.
Reference in New Issue View Git Blame Copy Permalink