Megamenu/README.md

SharePoint MegaMenu

Zentrale, barrierearme Portalnavigation aus SharePoint Managed Metadata für SharePoint Server Subscription Edition und SharePoint Server 2019.

Eigenschaft	Wert
Version	2.2.0
SharePoint Framework	1.4.1
Node.js für den Build	8.17.0
Moderne Seiten	SPFx Application Customizer
Klassische Seiten	separate ScriptLink-Variante
Paket	sharepoint/solution/mega-menu.sppkg

Funktionen

• zentrale Konfiguration pro Site Collection
• Termset-Auswahl bevorzugt per GUID, alternativ per Name
• drei Navigationsebenen
• zwei Darstellungsmodi: SharePoint-ähnliches Mega Menu und strukturelles Flyout
• benutzerdefinierte Sortierung aus dem Term Store
• Unterstützung für _Sys_Nav_SimpleLinkUrl, _Sys_Nav_TargetUrl und _Sys_Nav_HoverText
• Auflösung von ~sitecollection
• Markierung des aktuellen Navigationspfads
• Tastatur-, Fokus-, Maus- und Touch-Bedienung
• responsive Darstellung und Unterstützung reduzierter Bewegung
• Session-Cache mit konfigurierbarer Laufzeit
• Debug-Protokollierung ohne Ausgabe im Normalbetrieb
• Unterstützung moderner und klassischer SharePoint-Seiten

Architektur

App Catalog
└── zentral bereitgestelltes MegaMenu-SPFx-Bundle

Site Collection
└── SPSite.UserCustomAction
    ├── ComponentId
    └── ClientSideComponentProperties
        ├── termSetId / termSetName
        ├── cacheMinutes
        ├── menuMode
        └── debug

Moderne Seite                     Klassische Seite
└── Application Customizer        └── ScriptLink + Classic-Runtime

Die Site-Collection-Action ist die einzige Konfigurationsquelle. Es gibt keine versteckte Konfigurationsliste, keine MegaMenu-Konfiguration im Property Bag und keine Web-scoped Kopien. PortalSettings kann diese Action zentral lesen und aktualisieren.

Das SPFx-Paket verwendet skipFeatureDeployment: true. Es wird im App Catalog zentral bereitgestellt und nicht in Root Web oder Unterwebs über „App hinzufügen“ installiert.

Konfiguration

{
  "termSetId": "7948e6f9-7af4-431e-b6fe-328122f2746c",
  "termSetName": "Global Navigation",
  "cacheMinutes": 15,
  "cacheVersion": "1",
  "menuMode": "megaMenu",
  "debug": false
}

Property	Typ	Standard	Beschreibung
termSetId	String	leer	GUID des Termsets; hat Vorrang vor dem Namen
termSetName	String	leer	Fallback für bestehende Konfigurationen
cacheMinutes	Number	15	Cachezeit von 1 bis 1440 Minuten
cacheVersion	String	1	Frei wählbare Version zur sofortigen Invalidierung vorhandener Browser-Caches
menuMode	String	megaMenu	megaMenu oder flyout
debug	Boolean	false	ausführliche Browser-Konsolenausgaben

Mega Menu

"menuMode": "megaMenu" zeigt die zweite Ebene als breites, spaltenbasiertes Panel. Die dritte Ebene wird als Linkliste unter der jeweiligen Kategorie dargestellt.

Flyout

"menuMode": "flyout" zeigt die zweite Ebene als kompaktes Dropdown. Die dritte Ebene öffnet sich seitlich als strukturelles Flyout.

Lokale Term-Eigenschaften

Die folgenden Eigenschaften werden im Term Store als lokale benutzerdefinierte Eigenschaften am jeweiligen Term gepflegt:

Eigenschaft	Beispiel	Wirkung
MegaMenu.Hidden	true	Term und darunterliegender Navigationszweig werden nicht angezeigt
MegaMenu.OpenInNewWindow	true	Ziel wird sicher in einem neuen Browserfenster geöffnet
MegaMenu.Description	Anträge und Vorlagen	optionale Beschreibung einer Kategorie im Mega-Menu-Modus

Zusätzlich werden die SharePoint-Navigationseigenschaften _Sys_Nav_SimpleLinkUrl, _Sys_Nav_TargetUrl und _Sys_Nav_HoverText ausgewertet. Unsichere URL-Protokolle werden verworfen.

Build

npm install
npm run package

npm run package erstellt automatisch beide Ausgaben:

• das SPFx-Paket für moderne Seiten
• das Classic-Paket unter classic/dist/

Vor dem Packaging werden automatisch die Kernlogik-, Classic-Syntax- und statischen Asset-Tests ausgeführt. Bei einem Fehler wird kein Paket erzeugt.

Nur die Classic-Dateien neu erzeugen:

npm run build:classic

Erwartete Umgebung:

Node.js 8.17.0
npm 6.x
lokales Gulp 3.9.1

Das Ergebnis liegt unter:

sharepoint/solution/mega-menu.sppkg

Moderne Bereitstellung

1. mega-menu.sppkg in den Farm App Catalog hochladen beziehungsweise ersetzen.
2. Die Lösung zentral für alle Sites verfügbar machen.
3. MegaMenu nicht über „App hinzufügen“ in Inhaltswebsites installieren.
4. Pro gewünschter Site Collection eine Site-Collection-Action anlegen.

Beispiel für das Mega Menu:

.\deployment\add-megamenu.ps1 `
  -SiteUrl 'http://clshp001/sites/target' `
  -TermSetId '7948e6f9-7af4-431e-b6fe-328122f2746c' `
  -TermSetName 'Global Navigation' `
  -CacheMinutes 15 `
  -CacheVersion '1' `
  -MenuMode megaMenu

Beispiel für das Flyout:

.\deployment\add-megamenu.ps1 `
  -SiteUrl 'http://clshp001/sites/target' `
  -TermSetId '7948e6f9-7af4-431e-b6fe-328122f2746c' `
  -MenuMode flyout `
  -EnableDebug

Das Skript entfernt alte Web- und Site-Registrierungen, bereinigt die frühere Property-Bag-Konfiguration und erstellt genau eine neue Site-Collection-Action.

Classic Pages

Die Classic-Variante bleibt erhalten, weil ein SPFx Application Customizer nur in der modernen Oberfläche ausgeführt wird.

Das Classic-Paket wird bei npm run build und npm run package automatisch erzeugt. Es kann bei Bedarf auch separat gebaut werden:

npm run build:classic

Ausgabe:

classic/dist/
├── megamenu-classic.css
├── megamenu-services-standalone.js
├── megamenu-classic.js
└── classic-deployment.md

Die Classic-Runtime liest dieselben ClientSideComponentProperties der zentralen Site-Collection-Action und unterstützt ebenfalls beide Menümodi. Die Installationsdetails stehen in classic/classic-deployment.md.

Mobile Bedienung und Barrierefreiheit

• Unter 768 Pixeln wird die Navigation als Hamburger-Menü mit Accordion-Unterebenen dargestellt.
• Hover bleibt auf Desktop-Geräten als Komfortfunktion erhalten.
• Links und Schaltflächen zum Öffnen eines Untermenüs sind getrennt.
• Touch, Klick und Tastatur werden gleichwertig unterstützt.
• Escape schließt das aktive Menü; Links/Rechts wechselt zwischen Hauptpunkten.
• Fokusmarkierungen, Hochkontrast und reduzierte Bewegung werden unterstützt.

Cache und Mehrsprachigkeit

Der Session-Cache ist nach Site Collection, Termset, SharePoint-Oberflächensprache, Cache-Schema und cacheVersion getrennt. Nach einem temporären Taxonomy-Fehler kann der letzte abgelaufene, aber strukturell gültige Eintrag als Fallback verwendet werden. Eine geänderte cacheVersion erzwingt beim nächsten Laden einen neuen Cache.

Term-Labels sowie sichtbare Status- und ARIA-Texte werden anhand der aktuellen SharePoint-Sprache auf Deutsch oder Englisch ausgegeben.

Automatisierte Tests

npm test

Die Tests prüfen Term-Eigenschaften, URL-Sicherheit, externe Links, sprachabhängige Labels, Cache-Schlüssel, Hierarchieaufbau und Sortierung.

Styling

Das moderne Styling liegt in:

src/extensions/megaMenu/MegaMenu.module.scss

SPFx kompiliert diese Datei in das Bundle-CSS. Die eigenständige Classic-CSS liegt unter:

classic/megamenu-classic.css

Beide Varianten orientieren sich an SharePoint mit Segoe UI, neutralen Flächen, Theme-Farbe für den aktiven Pfad, kompakten Abständen und Fabric-kompatiblen Fokusmarkierungen.

Die wichtigsten CSS-Variablen können durch Custom Branding überschrieben werden:

:root {
  --megaMenuBarHeight: 44px;
  --megaMenuContentWidth: 1200px;
  --megaMenuFlyoutWidth: 288px;
  --megaMenuZIndex: 6000;
}

Das MegaMenu lädt bewusst keine externe cssUrl-Property. Kundenspezifische Gestaltung gehört in die Solution Custom Branding.

Diagnose

Mit "debug": true schreibt die moderne Extension Meldungen mit diesen Quellen:

[MegaMenuApplicationCustomizer]
[TaxonomyNavigationService]
[SPTermStorePickerService]
[MegaMenuRenderer]

Geladenes Bundle prüfen:

performance.getEntriesByType('resource')
  .map(function (entry) { return entry.name; })
  .filter(function (url) { return url.toLowerCase().indexOf('mega-menu') >= 0; });

Aktiven Modus prüfen:

document.getElementById('Mega-Menu').getAttribute('data-menu-mode');

Projektstruktur

MegaMenu/
├── classic/                         Classic-Runtime und CSS
├── config/                          SPFx-Buildkonfiguration
├── deployment/add-megamenu.ps1      zentrale Site-Registrierung
├── src/extensions/megaMenu/         Application Customizer, Renderer und SCSS
├── src/services/                    Taxonomy- und Navigationsdienste
├── build-classic.ps1
├── gulpfile.js
└── package.json

Versionshistorie

2.2.0

• mobiles Hamburger-/Accordion-Menü für Modern und Classic
• getrennte Link- und Untermenü-Schaltflächen für Touch und Tastatur
• sichere URL-Prüfung und Unterstützung externer Links
• lokale Term-Eigenschaften für Sichtbarkeit, neues Fenster und Beschreibung
• sprachabhängige Term-Labels, Status- und ARIA-Texte
• versionierter Cache pro Site Collection und Sprache mit Stale-Fallback
• automatisierte Kernlogiktests

2.1.0

• SharePoint-ähnliches, helles Navigationsdesign.
• Neue Property menuMode mit megaMenu und flyout.
• Eigenständiges Flyout-Rendering für zweite und dritte Ebene.
• Classic-Runtime und Classic-CSS auf beide Modi aktualisiert.
• Konfiguration auf eine Site-Collection-Action konsolidiert.
• Veraltete elements.xml, Azure-CDN-Konfiguration, Mock- und UserCustomAction-Service-Dateien entfernt.
• Bereitstellungs- und Classic-Buildskripte vereinfacht.

2.0.1

• Zentrale SPFx-Bereitstellung mit skipFeatureDeployment: true.
• Keine App-Installation in einzelnen Inhaltswebsites erforderlich.

2.0.0

• Neue Application-Customizer-ID c0abbffb-355d-4d4e-bd38-9e15fb811506.
• Alte On-Premises-Manifest- und Loader-Zuordnungen umgangen.