====== Welcome-Page Sections ======

Die zentrale Welcome-Page ist der erste Tab, den der Benutzer nach dem Start der Shell sieht. Sie zeigt Tastenkürzel, Schnellzugriffe und — wenn Add-ins installiert sind — zusätzliche Sektionen mit markenspezifischen Links und Aktionen. Add-ins deklarieren diese Sektionen im Manifest, und die Shell rendert sie als HTML-Blöcke unterhalb des eingebauten Inhalts.

Im Unterschied zu [[sidebarviews#welcome-inhalte|ViewsWelcome]], die Begrüßungsinhalte in leeren Sidebar-Views anzeigen, betrifft ''welcomePage'' die zentrale Willkommensseite im Dokumentbereich. Beide Mechanismen verwenden das ''command:''-Schema für Aktionslinks, aber sie adressieren unterschiedliche UI-Bereiche.

Zurück zur [[start|Contributions-Übersicht]] oder zur [[..:start|Hauptübersicht]].

===== Manifest-Deklaration =====

<code javascript>
"contributes": {
  "welcomePage": [
    {
      "title": "WIS Prüfungen",
      "icon": "codicon-shield",
      "order": 10,
      "contents": [
        {
          "label": "Prüfungen ausführen",
          "command": "wis.proofExec.open",
          "icon": "codicon-checklist"
        },
        {
          "label": "Prüfungen planen",
          "command": "wis.proofPlan.open",
          "icon": "codicon-calendar"
        },
        {
          "label": "Vorschau",
          "command": "wis.proofForecast.open",
          "icon": "codicon-telescope"
        }
      ]
    },
    {
      "title": "Berichte",
      "icon": "codicon-output",
      "order": 20,
      "contents": [
        {
          "label": "Excel-Export",
          "command": "wis.task.exportExcel",
          "icon": "codicon-file-binary"
        }
      ]
    }
  ]
}
</code>

===== Felder — Section =====

| **Feld** | **Pflicht** | **Beschreibung** |
| ''title'' | ja | Überschrift der Sektion. Wird als ''<h3>'' gerendert. Unterstützt [[..:lokalisierung|NLS]]-Platzhalter. |
| ''icon'' | nein | Codicon-Name für die Überschrift (derzeit reserviert, noch nicht gerendert). |
| ''order'' | nein | Sortierposition unter allen Sektionen. Niedrigere Werte stehen weiter oben. Standard: 0. |
| ''contents'' | ja | Array von Links, die in der Sektion als klickbare Einträge erscheinen. |

===== Felder — Link =====

| **Feld** | **Pflicht** | **Beschreibung** |
| ''label'' | ja | Anzeigetext des Links. Unterstützt [[..:lokalisierung|NLS]]-Platzhalter. |
| ''command'' | ja | Referenz auf einen deklarierten [[commands|Command]]. Klick löst diesen Command aus. |
| ''icon'' | nein | Codicon-Name neben dem Linktext (derzeit reserviert, noch nicht gerendert). |

===== Merge-Verfahren =====

Wenn mehrere Add-ins Sektionen zur Welcome-Page beitragen, sammelt der Host alle Einträge und sortiert sie nach ''order'' (numerisch aufsteigend). Sektionen mit gleichem ''order''-Wert erscheinen in Scan-Reihenfolge der Add-ins.

Jede Sektion wird als eigenständiger HTML-Block gerendert. Es gibt keine Gruppierung oder Verschmelzung von Sektionen verschiedener Add-ins — jede Sektion bleibt ein eigener Block mit eigener Überschrift.

===== Rendering =====

Die Shell rendert die Sektionen als HTML innerhalb der ''TIpHtmlPanel''-Komponente. Jeder Link wird als ''<a href="command:command.id">'' gerendert und nutzt denselben Dispatch-Mechanismus wie die eingebauten Quick Links: Klick → ''OnHotClick'' → Validierung des ''command:''-Schemas → ''ShellCommandRouter.ExecuteCommand()''.

Das Rendering erfolgt nur im **eingebauten Fallback-HTML**. Wenn eine externe ''welcome.html'' vorhanden ist (neben der EXE oder im ''media/''-Unterordner), hat diese Vorrang. In diesem Fall muss der Kunde die Plugin-Sektionen selbst in sein HTML einbauen.

===== Externe welcome.html =====

Der Host sucht eine externe Welcome-Datei in dieser Reihenfolge:

  - ''<EXE-Verzeichnis>/welcome.html''
  - ''<EXE-Verzeichnis>/media/welcome.html''

Wird eine Datei gefunden, wird sie direkt in ''TIpHtmlPanel'' geladen. Plugin-contributed Sections werden in diesem Fall **nicht** automatisch eingefügt — die externe Datei hat volle Kontrolle über den Inhalt.

Wird keine externe Datei gefunden, generiert die Shell das eingebaute HTML mit Tastenkürzel-Tabelle, Quick Links und allen Plugin-Sektionen.

===== Beispiel: Ergebnis mit zwei Add-ins =====

**Add-in A (WIS):**
<code javascript>
"welcomePage": [
  { "title": "WIS Prüfungen", "order": 10, "contents": [
    { "label": "Prüfungen ausführen", "command": "wis.proofExec.open" },
    { "label": "Prüfungen planen", "command": "wis.proofPlan.open" }
  ]}
]
</code>

**Add-in B (Assets):**
<code javascript>
"welcomePage": [
  { "title": "Anlagenverwaltung", "order": 20, "contents": [
    { "label": "Anlageliste öffnen", "command": "assets.list" },
    { "label": "Neue Anlage erfassen", "command": "assets.create" }
  ]}
]
</code>

Das Ergebnis auf der Welcome-Page:

<code>
  ┌──────────────────────────────────────────────┐
  │              WvdS Shell                      │
  │     Business Application GUI Host            │
  │                                              │
  │  Getting Started                             │
  │  Ctrl+Shift+P    Command Palette             │
  │  Ctrl+B          Toggle Sidebar              │
  │  Ctrl+J          Toggle Bottom Panel         │
  │                                              │
  │  Quick Links                                 │
  │  > Open Command Palette                      │
  │  > Toggle Sidebar                            │
  │  > Settings                                  │
  │                                              │
  │  WIS Prüfungen              (order: 10)      │
  │  > Prüfungen ausführen                       │
  │  > Prüfungen planen                          │
  │                                              │
  │  Anlagenverwaltung           (order: 20)     │
  │  > Anlageliste öffnen                        │
  │  > Neue Anlage erfassen                      │
  └──────────────────────────────────────────────┘
</code>

===== Abgrenzung zu ViewsWelcome =====

| **Merkmal** | **welcomePage** | **viewsWelcome** |
| Ziel-UI | Zentraler Welcome-Tab (Dokumentbereich) | Leere Sidebar-/Panel-Views |
| Sichtbarkeit | Immer, wenn Welcome-Tab offen | Nur wenn View leer ist |
| Format | Titel + Link-Array (JSON) | Markdown-Text mit ''[Text](command:id)'' |
| When-Klausel | Nicht unterstützt (immer sichtbar) | Unterstützt (bedingte Anzeige) |
| Manifest-Schlüssel | ''contributes.welcomePage'' | ''contributes.viewsWelcome'' |

Weiter zu [[sidebarviews|Sidebar-Views]] oder zurück zur [[start|Contributions-Übersicht]].