SharePoint MegaMenu

Barrierearme, dreistufige Portalnavigation auf Basis von SharePoint Managed Metadata für SharePoint Server Subscription Edition und SharePoint Server 2019.

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

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

UserCustomAction.ClientSideComponentProperties
                  │
                  ▼
MegaMenuApplicationCustomizer
                  │
                  ├── TaxonomyNavigationService
                  │       └── SPTermStorePickerService
                  │               └── Default Site Collection Term Store
                  │
                  └── MegaMenuRenderer
                          ├── semantische Navigation
                          ├── Fokus- und Tastatursteuerung
                          └── responsive Darstellung

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.

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:

{
  "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:

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.

npm install
npm run package

Alternativ einzeln:

gulp clean
gulp bundle --ship
gulp package-solution --ship

Das fertige Paket befindet sich anschließend unter:

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 dort zunächst web-scoped registriert und von PortalSettings erkannt.
4. Das Termset in PortalSettings konfigurieren.

Das folgende Skript ist nur erforderlich, wenn PortalSettings nicht verwendet wird oder eine vollständig skriptbasierte Vorkonfiguration gewünscht ist.

Empfohlen mit Termset-GUID:

.\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:

.\deployment\add-megamenu.ps1 `
  -SiteUrl 'https://sharepoint/sites/portal' `
  -TermSetName 'Global Navigation'

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:

#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:

: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

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

2.0.1

• Zentrale SPFx-Bereitstellung mit skipFeatureDeployment: true.
• Das MegaMenu-Paket muss nicht mehr als App in jedem Unterweb installiert werden.
• Feature-Framework-Registrierung aus dem Paket entfernt; die Aktivierung erfolgt zentral über PortalSettings oder das Deploymentskript.

2.0.0

• Neue Application-Customizer-ID c0abbffb-355d-4d4e-bd38-9e15fb811506, um alte On-Premises-Manifest- und Loader-Zuordnungen sicher zu umgehen.
• Eine zentrale MegaMenu-Konfiguration pro Site Collection im Property Bag des Root Webs.
• Web-scoped Runtime-Bindungen werden auf Root Web und alle vorhandenen Unterwebs synchronisiert.
• Aktivierungsskript entfernt alte Component IDs und kann fuer neue Unterwebs idempotent erneut ausgefuehrt werden.

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