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.
This commit is contained in:
Torsten Brendgen
381
README.md
381
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 <repository-url>
|
||||
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 `<nav aria-label="Hauptnavigation">`
|
||||
- native Listen- und Linksemantik
|
||||
- `aria-expanded` und `aria-haspopup` für aufklappbare Einträge
|
||||
- `aria-current="page"` für den aktuellen Navigationspfad
|
||||
- Öffnen über Leertaste oder Pfeil nach unten
|
||||
- Schließen über Escape
|
||||
- sichtbare Fokusindikatoren
|
||||
- Unterstützung von `prefers-reduced-motion` und kontrastreichen Darstellungen
|
||||
|
||||
- Entwicklung: Matthias Glubrecht
|
||||
- Framework: SharePoint Framework (Microsoft)
|
||||
- UI: Office UI Fabric (Microsoft)
|
||||
Bewusst wird kein `role="menubar"` verwendet: Eine Portalnavigation ist eine normale Navigation und kein Desktop-Menü-Widget. Dadurch bleiben native Browser- und Screenreader-Erwartungen erhalten.
|
||||
|
||||
## 📄 Lizenz
|
||||
## Fehlerdiagnose
|
||||
|
||||
tbd
|
||||
### „Die Navigation ist nicht konfiguriert“
|
||||
|
||||
## 🆘 Support
|
||||
Weder eine gültige `termSetId` noch ein `termSetName` ist gesetzt. UserCustomAction beziehungsweise PortalSettings-Konfiguration prüfen.
|
||||
|
||||
Bei Fragen oder Problemen:
|
||||
1. Issues im Repository erstellen
|
||||
2. Dokumentation und Troubleshooting-Bereich prüfen
|
||||
### „Die Navigation konnte nicht geladen werden“
|
||||
|
||||
- Existiert das Termset im Standard-Term-Store der Site Collection?
|
||||
- Ist die GUID korrekt?
|
||||
- Haben Benutzer Zugriff auf den Managed-Metadata-Service?
|
||||
- Enthält das Termset mindestens einen sichtbaren Term?
|
||||
- Ist der App-Catalog-Eintrag aktuell?
|
||||
|
||||
Für weitere technische Details kann vorübergehend `debug: true` gesetzt werden.
|
||||
|
||||
### Änderungen am Termset erscheinen verzögert
|
||||
|
||||
Die Navigation wird bis zu `cacheMinutes` im Session-Cache gehalten. Cache leeren oder Ablaufzeit abwarten.
|
||||
|
||||
### Zusätzliches CSS wird nicht geladen
|
||||
|
||||
- URL und Dateiberechtigungen prüfen.
|
||||
- Für externe Quellen HTTPS verwenden.
|
||||
- Browser-Konsole bei aktiviertem Debug-Modus prüfen.
|
||||
|
||||
## Upgrade von 1.0.x
|
||||
|
||||
- Bestehende `termSetName`-Konfigurationen funktionieren unverändert.
|
||||
- Der alte unversionierte Session-Cache wird nicht weiterverwendet.
|
||||
- `cacheMinutes` verwendet ohne Konfiguration den Wert 15.
|
||||
- Die eigene, nicht verwendete MegaMenu-Einstellungsseite wurde entfernt; PortalSettings ist der zentrale Konfigurationsweg.
|
||||
- Globale Event Listener werden beim Dispose der Extension entfernt.
|
||||
- Paket-, npm- und Dokumentationsversion wurden auf 1.1.0 vereinheitlicht.
|
||||
|
||||
## Classic Pages
|
||||
|
||||
Unter `classic/` befindet sich eine separate Kompatibilitätsimplementierung für klassische SharePoint-Seiten. Sie wird nicht vom SPFx-Bundle ausgeführt und besitzt einen eigenen Deploymentweg. Neue Funktionen sollten zuerst in der modernen SPFx-Variante umgesetzt und anschließend bewusst in die Classic-Variante übernommen werden.
|
||||
|
||||
## Projektstruktur
|
||||
|
||||
```text
|
||||
MegaMenu/
|
||||
├── config/ SPFx-Build- und Paketkonfiguration
|
||||
├── deployment/ Farm-/Site-Registrierung
|
||||
├── src/
|
||||
│ ├── extensions/megaMenu/ Application Customizer und Renderer
|
||||
│ └── services/ Taxonomy- und Datenmodelle
|
||||
├── classic/ optionale Classic-Kompatibilität
|
||||
├── build-classic.ps1 Classic-Build
|
||||
├── gulpfile.js
|
||||
└── package.json
|
||||
```
|
||||
|
||||
## Versionshistorie
|
||||
|
||||
### 1.1.0
|
||||
|
||||
- konsistente Verwendung des Default Site Collection Term Store
|
||||
- optionale Konfiguration per Termset-GUID
|
||||
- Cache-TTL und namensräumlich getrennter Session-Cache
|
||||
- korrekte Anwendung der Deprecated-/Availability-Filter
|
||||
- Prüfung der Taxonomy-HTTP-Antworten
|
||||
- Lifecycle-Cleanup für globale Event Listener
|
||||
- korrigierte Navigationssemantik und aktive Screenreader-Statusmeldungen
|
||||
- Validierung externer CSS-URLs
|
||||
- sichtbare Konfigurations- und Ladefehler
|
||||
- Entfernung des ungenutzten lokalen Settings-Panels
|
||||
- vereinheitlichte Projektversion und neue Build-/Deployment-Dokumentation
|
||||
|
||||
Reference in New Issue
Block a user