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.1.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,
  "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 |
| `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.

## 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/`

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

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