300 lines
11 KiB
Markdown
300 lines
11 KiB
Markdown
# SharePoint MegaMenu
|
|
|
|
Barrierearme, dreistufige Portalnavigation auf Basis von SharePoint Managed Metadata für SharePoint Server Subscription Edition und SharePoint Server 2019.
|
|
|
|
| Eigenschaft | Wert |
|
|
|---|---|
|
|
| Version | 1.1.4 |
|
|
| SharePoint Framework | SPFx 1.4.1 |
|
|
| Node.js | 8.17.0 |
|
|
| Zieloberfläche | Moderne SharePoint-Seiten |
|
|
| Paket | `sharepoint/solution/mega-menu.sppkg` |
|
|
|
|
## Funktionen
|
|
|
|
- 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
|
|
|
|
## Architektur
|
|
|
|
```text
|
|
UserCustomAction.ClientSideComponentProperties
|
|
│
|
|
▼
|
|
MegaMenuApplicationCustomizer
|
|
│
|
|
├── TaxonomyNavigationService
|
|
│ └── SPTermStorePickerService
|
|
│ └── Default Site Collection Term Store
|
|
│
|
|
└── MegaMenuRenderer
|
|
├── semantische Navigation
|
|
├── Fokus- und Tastatursteuerung
|
|
└── responsive Darstellung
|
|
```
|
|
|
|
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.
|
|
|
|
## Voraussetzungen
|
|
|
|
- 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
|
|
```
|
|
|
|
Alternativ einzeln:
|
|
|
|
```powershell
|
|
gulp clean
|
|
gulp bundle --ship
|
|
gulp package-solution --ship
|
|
```
|
|
|
|
Das fertige Paket befindet sich anschließend unter:
|
|
|
|
```text
|
|
sharepoint/solution/mega-menu.sppkg
|
|
```
|
|
|
|
## Deployment
|
|
|
|
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 dabei automatisch web-scoped registriert und von PortalSettings erkannt.
|
|
4. Das Termset in PortalSettings konfigurieren.
|
|
|
|
Das folgende Skript ist nur erforderlich, wenn ausdrücklich eine site-scoped Registrierung oder eine vollständig skriptbasierte Vorkonfiguration gewünscht ist.
|
|
|
|
Empfohlen mit Termset-GUID:
|
|
|
|
```powershell
|
|
.\deployment\add-megamenu.ps1 `
|
|
-SiteUrl 'https://sharepoint/sites/portal' `
|
|
-TermSetId '6f36a1a8-7bd8-4ed0-a22f-e219f4d2eacc' `
|
|
-TermSetName 'Global Navigation' `
|
|
-CacheMinutes 15
|
|
```
|
|
|
|
Abwärtskompatibel nur mit Namen:
|
|
|
|
```powershell
|
|
.\deployment\add-megamenu.ps1 `
|
|
-SiteUrl 'https://sharepoint/sites/portal' `
|
|
-TermSetName 'Global Navigation'
|
|
```
|
|
|
|
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.
|
|
|
|
## 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
|
|
#CustomNavigation { }
|
|
#Mega-Menu { }
|
|
.mega-menu-top-level { }
|
|
.mega-menu-top-item { }
|
|
.mega-menu { }
|
|
.mega-menu-grid { }
|
|
.mega-menu-category { }
|
|
.mega-menu-links { }
|
|
```
|
|
|
|
Viele Farben und Abstände können über CSS Custom Properties überschrieben werden, beispielsweise:
|
|
|
|
```css
|
|
:root {
|
|
--megaMenuNavBackground: #5f6f74;
|
|
--megaMenuNavTextColor: #ffffff;
|
|
--megaMenuPanelWidth: 1280px;
|
|
--megaMenuZIndex: 6000;
|
|
}
|
|
```
|
|
|
|
## Cache
|
|
|
|
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.
|
|
|
|
Für einen sofortigen administrativen Test kann der Session-Cache in den Browser-Entwicklertools gelöscht oder ein neues privates Browserfenster verwendet werden.
|
|
|
|
## Barrierefreiheit
|
|
|
|
- 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
|
|
|
|
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.
|
|
|
|
## Fehlerdiagnose
|
|
|
|
### „Die Navigation ist nicht konfiguriert“
|
|
|
|
Weder eine gültige `termSetId` noch ein `termSetName` ist gesetzt. UserCustomAction beziehungsweise PortalSettings-Konfiguration 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.
|
|
|
|
Bei aktiviertem Debug-Modus protokolliert MegaMenu den kompletten Startpfad mit den Quellen
|
|
`MegaMenuApplicationCustomizer`, `TaxonomyNavigationService`, `SPTermStorePickerService` und
|
|
`MegaMenuRenderer`. Dazu gehören die übergebenen Properties, Placeholder-Erkennung,
|
|
Taxonomy-Anfrage, Cache-Nutzung, Term-Anzahl, Containerwahl und vollständige Fehlerdetails.
|
|
Wenn keine dieser Meldungen erscheint, wurde das MegaMenu-Bundle nicht durch den SPFx-Loader
|
|
ausgeführt.
|
|
|
|
### Ä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.4
|
|
|
|
- Unnötige externe Abhängigkeit zu `@microsoft/sp-lodash-subset` entfernt.
|
|
- Terms werden beim Sortieren über eine lokale, SPFx-1.4.1-kompatible Pfadsuche zugeordnet.
|
|
- Verhindert, dass der Application Customizer bereits bei der Systemkomponenten-Auflösung übersprungen wird.
|
|
|
|
### 1.1.3
|
|
|
|
- Ausführliches, ausschließlich über `debug: true` aktiviertes Lifecycle-Logging ergänzt.
|
|
- Taxonomy-Anfragen, Session-Cache, Term-Filterung und Renderer werden nachvollziehbar protokolliert.
|
|
- Fehlerausgaben enthalten Name, Meldung und Stacktrace.
|
|
|
|
### 1.1.2
|
|
|
|
- `cssUrl` zugunsten der zentralen Custom-Branding-Solution entfernt
|
|
- deaktivierte, veraltete oder nicht zum Tagging verfügbare Terms werden ausgeblendet
|
|
- Cache-Namespace aktualisiert, damit alte deaktivierte Einträge nicht weiter angezeigt werden
|
|
|
|
### 1.1.1
|
|
|
|
- automatische Registrierung des MegaMenu Application Customizers bei der App-Installation
|
|
- direkte Erkennung durch PortalSettings ohne vorherigen Skriptaufruf
|
|
|
|
### 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
|