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

```text
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

```json
{
  "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

```powershell
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:

```powershell
npm run build:classic
```

Erwartete Umgebung:

```text
Node.js 8.17.0
npm 6.x
lokales Gulp 3.9.1
```

Das Ergebnis liegt unter:

```text
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:

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

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

```powershell
npm run build:classic
```

Ausgabe:

```text
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](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

```powershell
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:

```text
src/extensions/megaMenu/MegaMenu.module.scss
```

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

```text
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:

```css
: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:

```text
[MegaMenuApplicationCustomizer]
[TaxonomyNavigationService]
[SPTermStorePickerService]
[MegaMenuRenderer]
```

Geladenes Bundle prüfen:

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

Aktiven Modus prüfen:

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

## Projektstruktur

```text
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.