diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..497988f --- /dev/null +++ b/.gitignore @@ -0,0 +1,47 @@ +# Dependencies and local tools +node_modules/ +.tools/ + +# SPFx build output +lib/ +dist/ +temp/ +release/ +solution/ +sharepoint/solution/ +*.sppkg +*.tgz + +# Test output +coverage/ + +# Generated TypeScript files +*.resx.ts +*.scss.ts + +# Logs +logs/ +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Local environment files +.env +.env.* +!.env.example + +# Visual Studio and IDE files +.vs/ +.idea/ +.ntvs_analysis.dat +*.suo +*.user +bin/ +obj/ + +# Operating system files +.DS_Store +Thumbs.db +Desktop.ini + diff --git a/README.md b/README.md index 263d99e..a561214 100644 --- a/README.md +++ b/README.md @@ -1,199 +1,312 @@ -# 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 | 2.0.1 | +| 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 wird einmal pro Site Collection konfiguriert. Das Paket wird mit `skipFeatureDeployment: true` zentral über den App Catalog bereitgestellt, damit das SPFx-Bundle ohne eine App-Installation in jedem einzelnen Web verfügbar ist. PortalSettings speichert die zentrale Konfiguration im Property Bag des Root Webs. Eine Site-Collection-Action aktiviert das MegaMenu auf dem Root Web sowie auf vorhandenen und zukünftigen Unterwebs. Das MegaMenu selbst enthält keine eigene Administrationsoberfläche. -### 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, + "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 | +| `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 + +PortalSettings verwaltet `termSetId`, `termSetName`, `cacheMinutes` und `debug`. Individuelle Gestaltung wird nicht vom MegaMenu selbst geladen, sondern zentral über die Solution Custom Branding bereitgestellt. + +## 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 im Root Web der gewünschten Site Collection installieren. Der MegaMenu Application Customizer wird dort zunächst web-scoped registriert und von PortalSettings erkannt. +4. Das Termset in PortalSettings konfigurieren. -Das MegaMenu verfügt über ein Einstellungs-Panel, das über das Zahnrad-Icon (⚙️) im Menü zugänglich ist: +Das folgende Skript ist nur erforderlich, wenn PortalSettings nicht verwendet wird oder eine vollständig skriptbasierte Vorkonfiguration gewünscht 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 ``` -## 🎨 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 speichert die Konfiguration zentral unter `PortalSettings.MegaMenu.Configuration`, entfernt alte beziehungsweise doppelte Component IDs und synchronisiert die neue web-scoped Runtime-Bindung idempotent auf alle vorhandenen Webs. Fuer spaeter angelegte Unterwebs kann es ohne Nebenwirkungen erneut ausgefuehrt werden. + +## Individuelles Branding + +Zusätzliche Stylesheets werden zentral über die Solution Custom Branding eingebunden. Das MegaMenu besitzt bewusst keine eigene `cssUrl`-Property. + +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 `