# MOSAIC Blank Modul

## Uebersicht

`show_blank.php` ist der neutrale MOSAIC-Runner fuer freie fachliche Ablauflogik.
Er ist die MOSAIC-Entsprechung fuer Scriptcase-Blank-Apps, wenn weder `grid.php`
noch `form.php` fachlich passen.

Typische Einsatzfaelle:

- Dialoge mit eigener POST-Aktion
- fachliche Assistenten und Generatoren
- komplexe HTML-Ausgaben aus mehreren Tabellen
- Auswertungs- oder Druckvorstufen ohne Standard-CRUD
- Scriptcase-Blank-Code, der in MOSAIC wartbar bleiben soll

Es gibt bewusst keinen Builder fuer Blank-Apps. Blank-Apps werden direkt als
Konfigurationsdatei plus Function-Datei gepflegt.

## Dateinamen

Der Runner arbeitet mit dem Suffix `_blank`.

Beispiel:

- `befundbogen_blank.cfg`
- `befundbogen_blank_function.php`

Aufruf:

```text
_pgm/show_blank.php?project=<projekt>&modul=<name>&modul_path=<ordner>
```

Beispiel:

```text
_pgm/show_blank.php?project=argos&db=c5_argos&modul=befundbogen&modul_path=befundbogen
```

## Grundaufbau

Eine Blank-App besteht aus:

- `_pgm/show_blank.php`
  Runner fuer Bootstrap, Security, Request-Kontext, Action-Handling und Shell-Ausgabe
- `<name>_blank.cfg`
  deklarative Konfiguration fuer Titel, UI, Parameter, Aktionen und Rechte
- `<name>_blank_function.php`
  fachliche Hook-Datei fuer Pruefungen, Datenlogik, Aktionen und HTML-Ausgabe

## Config-Beispiel

```php
<?php

return [
    'app' => [
        'title' => 'Befundbogen',
        'headline' => 'BEFUNDBOGEN',
    ],
    'security' => true,
    'database_required' => true,
    'hooks_file' => 'befundbogen_blank_function.php',
    'ui' => [
        'render_shell' => true,
        'width' => '90%',
        'back_label' => 'Zurueck',
    ],
    'params' => [
        'selection_param' => 'selection_umfragen_string',
        'allowed_roles' => ['3', '4', '5', '7', '8'],
    ],
    'actions' => [
        'generate' => [
            'label' => 'Befundbogen erstellen',
            'right' => 'E',
        ],
    ],
    'permissions' => [
        'view' => true,
        'execute' => true,
    ],
];
```

## Standard-Konfigurationswerte

`show_blank.php` normalisiert fehlende Bereiche:

- `app.title`: `Blank`
- `app.headline`: leer
- `security`: `true`
- `ui.render_shell`: `true`
- `ui.width`: `90%`
- `ui.back_label`: `Zurueck`
- `params`: leeres Array
- `actions`: leeres Array
- `permissions.view`: `true`
- `permissions.execute`: `true`

## Request-Parameter

Unterstuetzte Standardparameter:

- `project`
  Projektname, z. B. `argos`
- `db`
  Datenbankverbindung aus `db_connection.lic`, z. B. `c5_argos`
- `modul`
  Modulstamm ohne `_blank.cfg`
- `modul_path`
  optionaler Projekt-Unterordner
- `cfg`
  optionaler alternativer Config-Dateiname; ohne Angabe wird `<modul>_blank.cfg` geladen

Weitere fachliche Parameter werden unveraendert in `context.request`, `context.get`
und `context.post` bereitgestellt.

## Security

`show_blank` ist in die MOSAIC-Security eingebunden:

- Suffix-Erkennung: `_blank.cfg`
- Runner: `show_blank`
- App-Key: `<project>|show_blank|<modul_path>|<modul>`

Beispiel:

```text
argos|show_blank|befundbogen|befundbogen
```

Beim Oeffnen prueft der Runner automatisch das Recht `V`.
POST-Aktionen pruefen zusaetzlich das in `actions.<aktion>.right` definierte Recht.
Wenn kein Recht angegeben ist, wird fuer Aktionen standardmaessig `E` verwendet.

Die fachliche Function-Datei sollte sensible Regeln weiterhin serverseitig pruefen,
z. B. Rollen, Besitzbeziehungen, Mandanten oder genau eine aktive Auswahl.

## Action-Handling

POST-Aktionen werden ueber `blank_action` oder `action` uebergeben.

Beispiel:

```html
<button type="submit" name="blank_action" value="generate">
    Befundbogen erstellen
</button>
```

Der Runner:

1. prueft CSRF, sofern `enforce_csrf_on_post()` vorhanden ist
2. prueft, ob die Aktion in `actions` konfiguriert ist
3. prueft das Aktionsrecht
4. ruft `onBeforeAction()`
5. ruft `onAction()` oder alternativ `onAction_<aktion>()`
6. rendert die Seite erneut

Rueckgabewerte von `onAction()`:

```php
return [
    'message' => 'Befundbogen wurde erstellt.',
    'class' => 'success',
];
```

`class` kann z. B. `success`, `warning`, `danger` oder `info` sein.

## Hook-Signaturen

Folgende Hooks werden unterstuetzt:

```php
function onApplicationInit(array &$context, array &$blankConfig): void
function onCheckSecurity(array &$context, array &$blankConfig): void
function onBeforeAction(array &$context, array &$blankConfig, string $action): mixed
function onAction(array &$context, array &$blankConfig, string $action): mixed
function onAction_generate(array &$context, array &$blankConfig): mixed
function onBeforeRender(array &$context, array &$blankConfig): void
function onRender(array &$context, array &$blankConfig): string
function onAfterRender(array &$context, array &$blankConfig, string &$body): void
```

`onAction_<aktion>()` ist eine optionale Alternative, wenn Aktionen getrennt
implementiert werden sollen. Ist `onAction()` vorhanden, wird es bevorzugt.

## Context

Der Runner stellt der Function-Datei folgenden Kontext bereit:

```php
$context = [
    'module_type' => 'blank',
    'runner' => 'show_blank',
    'project' => $project,
    'db_name' => $dbName,
    'db' => $db,
    'modul' => $module,
    'modul_path' => $modulePath,
    'cfg_file' => $cfgFile,
    'hook_file' => $hookFile,
    'request' => $_REQUEST,
    'get' => $_GET,
    'post' => $_POST,
    'session' => &$_SESSION,
    'action' => $action,
    'message' => &$message,
    'message_class' => &$messageClass,
];
```

## Rendering

Wenn `ui.render_shell` aktiv ist, rendert der Runner eine einfache MOSAIC-Shell
mit Bootstrap, Titel, Meldungsbereich und Inhaltsflaeche.

Die Function-Datei liefert nur den Body:

```php
function onRender(array &$context, array &$blankConfig): string
{
    return '<div class="alert alert-info">Blank-Ausgabe</div>';
}
```

Wenn eine App vollstaendig eigenes HTML ausgeben muss, kann `ui.render_shell`
auf `false` gesetzt werden.

## Fehlerbehandlung

Hook-Exceptions werden abgefangen:

- Security-Fehler aus `onApplicationInit()` oder `onCheckSecurity()` fuehren zu einer Fehlerseite.
- Action-Fehler werden als Meldung gerendert.
- Render-Fehler werden als sichtbare Fehlermeldung in der Shell angezeigt.

Dadurch sollen Blank-Apps keine rohen PHP-Fatals im Browser anzeigen.

## Einbindung in MOSAIC

`show_blank` ist an folgenden Kernstellen einzutragen:

- `_pgm/show_blank.php`
- `_pgm/security.php`
  - Runner-Suffix `_blank.cfg`
  - Runner-Whitelist
  - App-Erkennung fuer `iss_apps`
- `_pgm/iss_functions.php`
  - Hook-Kandidaten fuer `_blank_function.php`
- `_pgm/show_menu.php`
  - bekannter Runner fuer Menue-Links
- `_pgm/admin/create_menu.php`
  - Runner-Ableitung aus `_blank.cfg`
  - Dateityp-Badge `BLANK`
  - Runner-Auswahl `show_blank.php`

## Beispiel Argos Befundbogen

Der Argos-Befundbogen verwendet:

- `argos/befundbogen/befundbogen_blank.cfg`
- `argos/befundbogen/befundbogen_blank_function.php`

Fachliche Regeln:

- genau ein Fragebogen muss aktiv sein
- Zugriff nur fuer Rollen `3`, `4`, `5`, `7`, `8` (CLT Mitarbeiter, CLT Chef, Tierarzt/Therapeut und Ernaehrungsberater)
- der Master-Button `Befundbogen` in `umfrage_statistik_grid.cfg` ruft `show_blank.php` auf
- die Blank-App speichert die erzeugten HTML-Bloecke in `umfrage`

Gespeicherte Felder:

- `befundbogen_vom`
- `html_tierarzt`
- `html_tierhalter`
- `html_tier`
- `html_varianten`

Die Aktion `generate` baut die HTML-Bloecke aus `sec_users`, `tierhalter_tier`,
`k_rasse`, `umfrage` und `umfrage_statistik` und speichert sie serverseitig.

## Minimaler Link aus einem Button

```php
'link' => 'show_blank.php?project=argos&db=c5_argos'
    . '&modul=befundbogen&modul_path=befundbogen'
    . '&selection_umfragen_string=' . rawurlencode((string)$umfrageId)
    . '&iss_back_url=' . rawurlencode((string)($_SERVER['REQUEST_URI'] ?? '')),
```

## Empfehlung

`show_blank` sollte verwendet werden, wenn eine Anwendung fachlich ein freier
Ablauf ist und nicht primaer Tabellenpflege oder Listenanzeige.

Nicht verwenden fuer:

- einfache Tabellenlisten: `grid.php`
- normale Datensatzpflege: `form.php`
- filterbare Berichte mit Exporten: `show_report.php`
- Diagramme: `show_chart.php`
- Dashboards: `show_dashboard.php`

Damit bleibt `show_blank` ein schlanker Spezialrunner fuer bewusst freie Logik
und wird nicht zum Ersatz fuer bestehende Standard-Runner.
