# MOSAIC Connector Modul

## Uebersicht

Der Connector-Baustein besteht aus:

- `_pgm/admin/create_connector.php`
  Generator fuer `<name>_connector.cfg` und `<name>_connector_function.php`
- `<name>_connector.cfg`
  Konfiguration fuer Verbindung, Auth, Request-Aufbau und UI-Verhalten
- `<name>_connector_function.php`
  Optionale Hook-Datei im MOSAIC-Stil
- `_pgm/show_connector.php`
  Runner fuer ausgehende HTTP-Aufrufe mit HTML- und JSON-Ausgabe

## Generator

`create_connector.php` ist als komfortabler visueller Builder ausgelegt:

- Projekt, Zielordner und Dateiname werden wie in anderen MOSAIC-Generatoren gepflegt
- das Suffix `_connector.cfg` wird automatisch erzwungen
- die Hook-Datei `<name>_connector_function.php` wird passend zum Modulnamen erzeugt
- Header, Query-Parameter und Body-Felder werden ueber visuelle Editor-Bloecke gepflegt
- Platzhalter wie `{{customer_id}}` sind in URL, Pfad, Headern, Query, Body und Raw-Body erlaubt
- Systemprofile aus `mosaic_config.lic` oder `config.php` werden erkannt und koennen als Profil referenziert werden

## Grundaufbau der Config

```php
return [
    'app' => [
        'type' => 'connector',
        'version' => 1,
        'title' => 'CRM Connector',
    ],
    'description' => 'Liest Stammdaten aus dem CRM',
    'hooks_file' => 'crm_connector_function.php',
    'profile' => 'crm',
    'connection' => [
        'base_url' => 'https://api.example.com',
        'path' => '/v1/customers/{{customer_id}}',
        'method' => 'GET',
        'timeout' => 30,
        'verify_ssl' => true,
        'follow_redirects' => true,
        'response_mode' => 'json',
    ],
    'auth' => [
        'mode' => 'bearer',
        'header_name' => 'Authorization',
        'query_name' => 'api_key',
        'token_prefix' => 'Bearer',
        'token' => '',
        'username' => '',
        'password' => '',
        'api_key' => '',
    ],
    'request' => [
        'headers' => [
            ['name' => 'Accept', 'value' => 'application/json', 'from_request' => '', 'enabled' => true],
        ],
        'query' => [
            ['name' => 'include', 'value' => 'contacts', 'from_request' => '', 'enabled' => true],
        ],
        'body_mode' => 'none',
        'body' => [],
        'raw_body' => '',
        'content_type' => '',
    ],
    'ui' => [
        'headline' => 'CRM Connector',
        'intro' => 'Ruft externe Kundendaten ab.',
        'submit_label' => 'Anfrage starten',
        'show_form' => true,
        'auto_execute' => false,
        'show_request_payload' => true,
        'show_response_headers' => false,
        'show_status_badge' => true,
        'empty_response_message' => 'Noch keine Antwort vorhanden.',
    ],
    'logging' => [
        'enabled' => false,
    ],
];
```

## Systemprofile

Optional koennen in der Projekt-Konfiguration Profile hinterlegt werden:

```php
'connector_profiles' => [
    'crm' => [
        'connection' => [
            'base_url' => 'https://api.example.com',
            'timeout' => 20,
            'response_mode' => 'json',
        ],
        'auth' => [
            'mode' => 'bearer',
            'token' => 'secret-token',
        ],
        'request' => [
            'headers' => [
                ['name' => 'Accept', 'value' => 'application/json', 'enabled' => true],
            ],
        ],
    ],
],
```

Der Runner verwendet das Profil als Default-Quelle und laesst konkrete Modulwerte danach ueberschreiben.
Leere Modulwerte koennen dadurch bewusst durch Systemwerte gefuellt werden.

## Unterstuetzte Auth-Modi

- `none`
- `bearer`
- `basic`
- `api_key_header`
- `api_key_query`

## Hooks

Die automatisch erzeugte Function-Datei enthaelt diese Hooks:

- `onApplicationInit`
- `onCheckSecurity`
- `onBeforeResolve`
- `onBeforeRequest`
- `onAfterResponse`
- `onBeforeRender`
- `onAfterRender`

Alle Hooks arbeiten mit Referenzen und koennen sowohl die Connector-Konfiguration als auch Request- und Response-Payload anpassen.

## Aufruf

HTML-Ausgabe:

```text
_pgm/show_connector.php?project=demo&modul=crm
```

JSON-Ausgabe:

```text
_pgm/show_connector.php?project=demo&modul=crm&format=json&execute=1&customer_id=42
```

## Menu und Dashboard

- `create_menu.php` erkennt `_connector.cfg` automatisch und setzt `show_connector.php` als Runner
- `show_menu.php` folgt im Kern dem einheitlichen `show_*`-Konzept; Connector-Module laufen dort ueber `show_connector.php`
- `show_dashboard.php` kann `_connector`-Module direkt in Dashboard-Widgets aufloesen
## Runner-Stand im Kern

Stand April 2026 gilt im MOSAIC-Kern ein einheitliches Runner-Schema:

- `grid.php`, `form.php` und `show_egrid.php` bilden die kanonischen CRUD-Einstiege; `show_egrid.php` delegiert intern an `egrid.php`
- alle anderen fachlichen Runner verwenden konsequent das Praefix `show_`
- typische Beispiele sind `show_menu.php`, `show_dashboard.php`, `show_report.php`, `show_chart.php`, `show_login.php` und `show_v_menu.php`
- fruehere Alt-Namen sind nicht mehr Bestandteil des aktiven Kernbereichs