From 97d2b6b5d2bca59768172331189d8881404adf4f Mon Sep 17 00:00:00 2001 From: Torsten Brendgen Date: Thu, 16 Jul 2026 22:43:31 +0200 Subject: [PATCH 01/10] Update MegaMenu Application Customizer: Version bump to 1.1.0, localization support added, and unnecessary files removed - Deleted obsolete localization file for English (en-us). - Updated version number from 1.0.4 to 1.1.0 in manifests.js and manifests.json. - Added localization support for German (de-de) in a new localization file. - Removed unnecessary dependencies from manifests. - Added .gitignore to exclude build artifacts and temporary files. --- .gitignore | 10 + README.md | 381 +++++++++++------- config/package-solution.json | 6 +- deployment/add-megamenu.ps1 | 13 +- ...-bb2d-491f-aba3-cd51c19a299b.manifest.json | 17 +- dist/mega-menu-application-customizer.js | 6 +- dist/mega-menu-application-customizer.js.map | 1 - lib/extensions/megaMenu/MegaMenu.module.css | 2 +- .../megaMenu/MegaMenu.module.scss.d.ts | 5 +- .../megaMenu/MegaMenu.module.scss.js | 5 +- .../megaMenu/MegaMenu.module.scss.js.map | 2 +- .../MegaMenuApplicationCustomizer.d.ts | 30 +- .../megaMenu/MegaMenuApplicationCustomizer.js | 152 +++++-- .../MegaMenuApplicationCustomizer.js.map | 2 +- lib/extensions/megaMenu/MegaMenuRenderer.d.ts | 28 +- lib/extensions/megaMenu/MegaMenuRenderer.js | 324 +++++++++------ .../megaMenu/MegaMenuRenderer.js.map | 2 +- lib/extensions/megaMenu/MegaMenuSettings.d.ts | 25 -- lib/extensions/megaMenu/MegaMenuSettings.js | 223 ---------- .../megaMenu/MegaMenuSettings.js.map | 1 - lib/extensions/megaMenu/loc/en-us.js | 6 +- .../ISPTermStorePickerServiceProps.d.ts | 1 + lib/services/SPTermStorePickerService.d.ts | 10 +- lib/services/SPTermStorePickerService.js | 94 ++++- lib/services/SPTermStorePickerService.js.map | 2 +- lib/services/TaxonomyNavigationService.d.ts | 7 +- lib/services/TaxonomyNavigationService.js | 76 ++-- lib/services/TaxonomyNavigationService.js.map | 2 +- .../UserCustomActionService.d.ts | 3 +- .../UserCustomActionService.js | 16 +- .../UserCustomActionService.js.map | 2 +- package-lock.json | 2 +- package.json | 7 +- src/extensions/megaMenu/MegaMenu.module.scss | 20 +- .../megaMenu/MegaMenu.module.scss.ts | 2 - .../megaMenu/MegaMenuApplicationCustomizer.ts | 119 +++++- src/extensions/megaMenu/MegaMenuRenderer.ts | 62 ++- src/extensions/megaMenu/MegaMenuSettings.ts | 210 ---------- src/extensions/megaMenu/loc/de-de.js | 7 + src/extensions/megaMenu/loc/en-us.js | 6 +- src/extensions/megaMenu/loc/myStrings.d.ts | 2 + .../ISPTermStorePickerServiceProps.ts | 3 +- src/services/MegaMenuDebug.ts | 5 +- src/services/SPTermStorePickerService.ts | 109 ++++- src/services/TaxonomyNavigationService.ts | 43 +- .../abc3361f-bb2d-491f-aba3-cd51c19a299b.json | 2 +- ...omizer_392adab1c3d9b92b7b82b0eaa3c10004.js | 11 - ...omizer_772e63bec1cc7a1691e79694f57b9245.js | 11 - ...omizer_a8c5b6b10667569479c9117e39176bd7.js | 11 - ...omizer_afd45381aceb3466a423d662fdb1e30b.js | 11 - ..._en-us_6adac6d498d12e2a464a299b650578f1.js | 5 - temp/manifests.js | 17 +- temp/manifests.json | 17 +- 53 files changed, 1071 insertions(+), 1065 deletions(-) create mode 100644 .gitignore delete mode 100644 dist/mega-menu-application-customizer.js.map delete mode 100644 lib/extensions/megaMenu/MegaMenuSettings.d.ts delete mode 100644 lib/extensions/megaMenu/MegaMenuSettings.js delete mode 100644 lib/extensions/megaMenu/MegaMenuSettings.js.map delete mode 100644 src/extensions/megaMenu/MegaMenuSettings.ts create mode 100644 src/extensions/megaMenu/loc/de-de.js delete mode 100644 temp/deploy/mega-menu-application-customizer_392adab1c3d9b92b7b82b0eaa3c10004.js delete mode 100644 temp/deploy/mega-menu-application-customizer_772e63bec1cc7a1691e79694f57b9245.js delete mode 100644 temp/deploy/mega-menu-application-customizer_a8c5b6b10667569479c9117e39176bd7.js delete mode 100644 temp/deploy/mega-menu-application-customizer_afd45381aceb3466a423d662fdb1e30b.js delete mode 100644 temp/deploy/megamenu-megamenuapplicationcustomizerstrings_en-us_6adac6d498d12e2a464a299b650578f1.js diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..94af1c1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,10 @@ +node_modules/ +.tools/ +lib/ +dist/ +temp/ +release/ +sharepoint/solution/ +*.sppkg +*.tgz +npm-debug.log* diff --git a/README.md b/README.md index 263d99e..045229f 100644 --- a/README.md +++ b/README.md @@ -1,199 +1,278 @@ -# SharePoint MegaMenu Extension +# SharePoint MegaMenu -**Version:** 1.0.2 -**Framework:** SharePoint Framework (SPFx) 1.4.1 -**Node.js:** v8.17.0 +Barrierearme, dreistufige Portalnavigation auf Basis von SharePoint Managed Metadata für SharePoint Server Subscription Edition und SharePoint Server 2019. -Eine moderne, barrierefreie Mega-Menü-Lösung für SharePoint 2019 oder SharePoint SE als ApplicationCustomizer Extension. +| Eigenschaft | Wert | +|---|---| +| Version | 1.1.0 | +| SharePoint Framework | SPFx 1.4.1 | +| Node.js | 8.17.0 | +| Zieloberfläche | Moderne SharePoint-Seiten | +| Paket | `sharepoint/solution/mega-menu.sppkg` | -## 🌟 Features +## Funktionen -- **3-stufige Navigationshierarchie** basierend auf SharePoint Managed Metadata (Taxonomy) -- **Responsive Design** mit automatischer Anpassung an verschiedene Bildschirmgrößen -- **Barrierefreiheit** mit vollständiger Tastaturnavigation und Screenreader-Unterstützung -- **Einstellungs-Panel** für Administratoren zur Konfiguration -- **Externe CSS-Unterstützung** für individuelle Anpassungen -- **Office UI Fabric Integration** für konsistente SharePoint-Optik +- Dreistufige Navigation aus einem Managed-Metadata-Termset +- Auswahl des Termsets per GUID oder, abwärtskompatibel, per Name +- Benutzerdefinierte Sortierung aus dem Term Store +- Unterstützung der Navigations-Eigenschaften `_Sys_Nav_SimpleLinkUrl`, `_Sys_Nav_TargetUrl` und `_Sys_Nav_HoverText` +- Auflösung von `~sitecollection` in Navigations-URLs +- Markierung des aktuellen Menüpunktes und seiner übergeordneten Einträge +- Bedienung mit Maus, Tastatur und Touch +- Responsive Darstellung +- Optionales zusätzliches Stylesheet +- Taxonomy-Cache mit konfigurierbarer Ablaufzeit +- Bereinigter SPFx-Lifecycle ohne verbleibende globale Event Listener +- Deutsche und englische Statusmeldungen -## 📋 Voraussetzungen +## Architektur -- SharePoint 2019 oder SharePoint SE (Subscription Edition) -- Node.js v8.17.0 (empfohlen) -- SharePoint Framework Development Tools (SPFx 1.4.1) +```text +UserCustomAction.ClientSideComponentProperties + │ + ▼ +MegaMenuApplicationCustomizer + │ + ├── TaxonomyNavigationService + │ └── SPTermStorePickerService + │ └── Default Site Collection Term Store + │ + └── MegaMenuRenderer + ├── semantische Navigation + ├── Fokus- und Tastatursteuerung + └── responsive Darstellung +``` -## 🚀 Installation & Entwicklung +Das MegaMenu liest seine Laufzeitkonfiguration aus der site-scoped UserCustomAction. Es enthält keine eigene Administrationsoberfläche. Die zentrale Pflege soll über die separate Solution **PortalSettings** erfolgen. -### 1. Repository klonen und Abhängigkeiten installieren +## Voraussetzungen -```bash -git clone -cd MegaMenu +- SharePoint Server Subscription Edition oder SharePoint Server 2019 +- konfigurierter App Catalog +- konfigurierter App Management Service +- ein Termset im Standard-Term-Store der Site Collection +- Leseberechtigung der Benutzer auf den Managed-Metadata-Service +- für Entwicklung und Build: Node.js 8.17.0 und eine zu SPFx 1.4.1 passende npm-Version + +## Konfiguration + +Die UserCustomAction unterstützt folgende `ClientSideComponentProperties`: + +```json +{ + "termSetId": "6f36a1a8-7bd8-4ed0-a22f-e219f4d2eacc", + "termSetName": "Global Navigation", + "cacheMinutes": 15, + "cssUrl": "/SiteAssets/megamenu/megamenu-custom.css", + "debug": false +} +``` + +| Eigenschaft | Typ | Standard | Beschreibung | +|---|---:|---:|---| +| `termSetId` | GUID | leer | Bevorzugte, eindeutige Identifikation des Termsets | +| `termSetName` | String | leer | Rückwärtskompatibler Fallback, wenn keine gültige `termSetId` vorhanden ist | +| `cacheMinutes` | Zahl | `15` | Gültigkeit des Session-Caches, zulässig sind 1 bis 1440 Minuten | +| `cssUrl` | String | leer | Relatives/same-origin Stylesheet oder externe HTTPS-Adresse | +| `debug` | Boolean | `false` | Aktiviert zusätzliche Konsolenausgaben | + +`termSetId` hat Vorrang vor `termSetName`. Für neue Installationen wird die GUID empfohlen, weil Termset-Namen nicht zwingend eindeutig sind. + +### Kompatibilität mit PortalSettings + +Die bisherige PortalSettings-Version verwaltet `termSetName`, `cssUrl` und `debug`. Das MegaMenu 1.1.0 bleibt damit vollständig lauffähig und verwendet für nicht vorhandene `cacheMinutes` automatisch 15 Minuten. + +Damit auch `termSetId` und `cacheMinutes` zentral bearbeitet werden können, muss das MegaMenu-Formular in PortalSettings um diese beiden Eigenschaften ergänzt werden. Bis dahin können sie über das Deployment-Skript gesetzt werden. Speichert eine ältere PortalSettings-Version anschließend erneut, werden die beiden noch unbekannten Eigenschaften entfernt; das MegaMenu fällt dann kontrolliert auf `termSetName` und den Standard-Cache zurück. + +## Termset-Aufbau + +Die Darstellung unterstützt drei Ebenen: + +```text +Ebene 1: Hauptnavigation +├── Ebene 2: Kategorie +│ ├── Ebene 3: Link +│ └── Ebene 3: Link +└── Ebene 2: Kategorie +``` + +Für Zieladressen werden die lokalen benutzerdefinierten Eigenschaften des Terms ausgewertet: + +1. `_Sys_Nav_SimpleLinkUrl` +2. `_Sys_Nav_TargetUrl` + +Optional kann `_Sys_Nav_HoverText` als ergänzender Hilfetext verwendet werden. Veraltete Terms werden nicht angezeigt. Terms, die nicht für Tagging verfügbar sind, bleiben für Navigationsszenarien sichtbar. + +## Build + +SPFx 1.4.1 verwendet die Legacy-Gulp-Toolchain. Neuere Node-Versionen sind nicht kompatibel. + +```powershell npm install +npm run package ``` -### 2. Entwicklungsserver starten +Alternativ einzeln: -```bash -gulp serve -``` - -### 3. Produktionspaket erstellen - -```bash +```powershell gulp clean gulp bundle --ship gulp package-solution --ship ``` -## 📁 Projektstruktur +Das fertige Paket befindet sich anschließend unter: -``` -src/ -├── extensions/ -│ └── megaMenu/ -│ ├── MegaMenuApplicationCustomizer.ts # Haupteinstiegspunkt -│ ├── MegaMenuRenderer.ts # Menü-Rendering-Logik -│ ├── MegaMenuSettings.ts # Einstellungs-Panel -│ └── MegaMenu.css # Styling -├── services/ -│ ├── TaxonomyNavigationService.ts # Taxonomy-Datenabfrage -│ ├── UserCustomActionService/ # UserCustomAction-Verwaltung -│ └── ... -└── deployment/ - ├── add-megamenu.ps1 # Installations-Script - └── remove-megamenu.ps1 # Deinstallations-Script +```text +sharepoint/solution/mega-menu.sppkg ``` -## ⚙️ Konfiguration +## Deployment -### Einstellungs-Panel (Admin-Bereich) +1. `mega-menu.sppkg` in den App Catalog laden. +2. Die Solution freigeben. +3. Die App in der gewünschten Site Collection installieren. +4. Das MegaMenu site-scoped registrieren. -Das MegaMenu verfügt über ein Einstellungs-Panel, das über das Zahnrad-Icon (⚙️) im Menü zugänglich ist: - -1. **Name des Navigations-Termsets**: Der Name des Managed Metadata Termsets, das als Datenquelle dient -2. **Pfad zu zusätzlicher CSS-Datei**: Optional - URL zu einer benutzerdefinierten CSS-Datei - -### PowerShell-Deployment +Empfohlen mit Termset-GUID: ```powershell -# Installation -.\src\deployment\add-megamenu.ps1 - -# Deinstallation -.\src\deployment\remove-megamenu.ps1 +.\deployment\add-megamenu.ps1 ` + -SiteUrl 'https://sharepoint/sites/portal' ` + -TermSetId '6f36a1a8-7bd8-4ed0-a22f-e219f4d2eacc' ` + -TermSetName 'Global Navigation' ` + -CacheMinutes 15 ` + -CssUrl '/SiteAssets/megamenu/megamenu-custom.css' ``` -## 🎨 Anpassungen +Abwärtskompatibel nur mit Namen: -### CSS-Customization +```powershell +.\deployment\add-megamenu.ps1 ` + -SiteUrl 'https://sharepoint/sites/portal' ` + -TermSetName 'Global Navigation' +``` -Das MegaMenu kann über externe CSS-Dateien angepasst werden. Wichtige CSS-Klassen: +Das Skript entfernt ältere web-scoped Registrierungen derselben Komponente und erstellt beziehungsweise aktualisiert eine site-scoped UserCustomAction mit dem Description-Tag `MSFT-Custom-Solution:MegaMenu`. Dieses Tag wird von PortalSettings zur Erkennung verwendet. + +## Zusätzliches CSS + +Zulässig sind: + +- serverrelative oder relative Pfade derselben SharePoint-Origin, +- absolute URLs derselben Origin, +- externe URLs ausschließlich über HTTPS. + +Nicht-HTTP(S)-Schemes und unverschlüsselte externe HTTP-Adressen werden zur Laufzeit verworfen. + +Die wichtigsten CSS-Klassen sind: ```css -/* Haupt-Container */ +#CustomNavigation { } #Mega-Menu { } - -/* Top-Level Menüpunkte */ -#Mega-Menu > ul > li > a { } - -/* Mega-Menü Dropdown */ +.mega-menu-top-level { } +.mega-menu-top-item { } .mega-menu { } - -/* Kategorien im Dropdown */ +.mega-menu-grid { } .mega-menu-category { } - -/* Links in Kategorien */ -.mega-menu-category ul li a { } - -/* Einstellungs-Panel */ -.mm-settings-panel { } +.mega-menu-links { } ``` -### Accessibility Features +Viele Farben und Abstände können über CSS Custom Properties überschrieben werden, beispielsweise: -- **Skip-Links** für Screenreader -- **ARIA-Rollen** und Labels -- **Fokus-Management** mit sichtbaren Fokus-Indikatoren -- **Tastaturnavigation** mit Tab/Shift+Tab/Escape -- **High Contrast Modus** Unterstützung - -## 🔧 Build-Befehle - -| Befehl | Beschreibung | -|--------|-------------| -| `gulp serve` | Entwicklungsserver mit Live-Reload | -| `gulp build` | Entwicklungs-Build (Debug-Modus) | -| `gulp bundle --ship` | Produktions-Build (Optimiert) | -| `gulp package-solution --ship` | SharePoint Package (.sppkg) erstellen | -| `gulp clean` | Build-Artifacts löschen | -| `gulp test` | Unit-Tests ausführen | - -## 📦 Deployment - -1. **Paket erstellen:** - ```bash - gulp clean && gulp bundle --ship && gulp package-solution --ship - ``` - -2. **SharePoint App Catalog:** - - `.sppkg` Datei aus `sharepoint/solution/` hochladen - - App genehmigen und für alle Sites verfügbar machen - -3. **Site-spezifische Aktivierung:** - - PowerShell-Scripts verwenden - -## 🐛 Troubleshooting - -### Häufige Probleme - -**Problem:** Menü wird nicht angezeigt -**Lösung:** Termset-Name in den Einstellungen prüfen - -**Problem:** CSS-Styling funktioniert nicht -**Lösung:** Externe CSS-URL und CORS-Einstellungen überprüfen - -**Problem:** Build-Fehler -**Lösung:** Node.js Version prüfen (v8.17.0 empfohlen) - -### Debug-Modus - -```bash -# Detaillierte Build-Ausgabe -gulp bundle --verbose - -# TypeScript-Fehler anzeigen -gulp build +```css +:root { + --megaMenuNavBackground: #5f6f74; + --megaMenuNavTextColor: #ffffff; + --megaMenuPanelWidth: 1280px; + --megaMenuZIndex: 6000; +} ``` -## 🔄 Versionshistorie +## Cache -### v1.0.2 (Aktuell) -- Einstellungs-Panel implementiert -- Fokus-Management verbessert -- CSS-Optimierungen für SharePoint-Konsistenz -- Barrierefreiheit-Verbesserungen +Das geladene Termset wird im `sessionStorage` des Browsers gespeichert. Der Schlüssel ist mit `MegaMenu:TermSet:` namensräumlich getrennt. Nach Ablauf von `cacheMinutes` wird das Termset automatisch neu geladen. -### v1.0.1 -- Responsive Design hinzugefügt -- Performance-Optimierungen +Für einen sofortigen administrativen Test kann der Session-Cache in den Browser-Entwicklertools gelöscht oder ein neues privates Browserfenster verwendet werden. -### v1.0.0 -- Initiale Release -- 3-stufige Navigation -- Grundlegende Accessibility +## Barrierefreiheit -## 👥 Mitwirkende +- semantisches `