KPI-Dashboards

Kennzahl-Kacheln mit Vergleichswerten, eingebetteten Sub-Dashboards und PWA-Install.

KPI-Dashboards bestehen aus einer Reihe von Tiles. Jede Kachel zeigt eine Kennzahl mit optionalem Vergleichswert (gestern, letzte Woche), Trend-Indikator und Ampel-Farbe. Spezial-Tiles (group, forecast, embed, row_break) erweitern das Grundgerüst.

#Grundgerüst

'kpi' => [
    'title' => 'KPI Dashboard',
    'type' => 'kpi',
    'access' => 'login',
    'datasource' => [
        'type' => 'google_sheet',
        'slug' => 'kpi',
        'sheetName' => 'Tabellenblatt1',
        'cache_ttl' => 20,         // = Browser-Refresh-Intervall in Sekunden
        'row' => 'last',           // letzte Zeile = aktuelle Werte
    ],
    'tiles' => [ /* siehe unten */ ],
],

Bei row => 'last' wird die letzte Zeile des Sheets als „Aktueller Stand" gelesen — typisch wenn ein Cron-Job laufend neue Zeilen anhängt.

#Standard-Tile

[
    'title' => 'Verpackt heute',
    'column' => 'Verpackt heute',
    'compare_column' => 'Verpackt gestern Vergleich',
    'format' => 'number',
    'size' => 'large',
    'span' => 3,
    'compare_label' => 'gestern um diese Zeit',
    'compare_mode' => 'higher_is_better',
],

#Spezial-Tile-Typen

#group — Trennzeile mit Titel

['type' => 'group', 'title' => 'Services', 'icon' => '🖥️'],

Erscheint als Banner zwischen den Kacheln-Reihen.

#forecast — Hochrechnung auf Tagesende

[
    'title' => 'Forecast heute',
    'type' => 'forecast',
    'today_column' => 'Verpackt heute',
    'yesterday_compare_column' => 'Verpackt gestern Vergleich',
    'yesterday_total_column' => 'Verpackt gestern',
    'format' => 'number',
    'size' => 'medium',
    'compare_mode' => 'neutral',
],

Logik: today / yesterday_compare * yesterday_total = erwartetes Tagesende. Vergleichswert = yesterday_total.

#extras — Mehrere Werte in einer Tile

Untergeordnete Kennzahlen unter dem Hauptwert:

[
    'title' => 'JTL API',
    'column' => 'JTL API Status',
    'format' => 'text',
    'extras' => [
        ['label' => 'Response', 'column' => 'JTL API ms', 'suffix' => 'ms'],
    ],
],

#embed — Anderes Dashboard als iframe einbetten

Lädt ein anderes Dashboard im Embed-Modus (ohne Header/Controls) als iframe. Sub-Token wird serverseitig aus der Config gezogen — der KPI-Token reicht aus, um auch eingebettete Dashboards zu sehen.

[
    'type' => 'embed',
    'dashboard_slug' => 'shipping_progress',
    'span' => 6,            // 1..12, halbe Breite
    'height' => 380,        // px
],

Mehrere embed-Tiles direkt nacheinander landen automatisch in einer eigenen 12-Spalten-Reihe (embed-row), die unabhängig vom KPI-Tile-Grid ist. Spans 1..12 möglich.

#row_break — Reihe mit anderer Spalten-Anzahl

Standard-KPI-Grid hat 3 Spalten. row_break schaltet auf eine andere Anzahl um — sinnvoll z.B. für eine 4×25%-Reihe:

[
    'type' => 'row_break',
    'cols' => 4,             // 3 oder 4
],

Alle nachfolgenden Tiles bis zum nächsten row_break oder embed laufen im neuen Grid. Ein weiterer row_break mit cols => 3 schaltet zurück.

#Format-Typen

#Compare-Modes

Farbgebung folgt dem Darkmode-Theme (#66BB6A grün, #EF5350 rot, transparente Backgrounds), passend zu den Chart-Ampelfarben.

#Layout

Tiles werden in ein Grid gerendert. Default: 3 Spalten, mit span: 1..3 oder span: 4 für die volle Breite. Das Grid ist responsive (2 Spalten auf Tablet, 1 auf Mobile).

Mit row_break cols: 4 kannst du pro Reihe auf 4 Spalten umstellen — Tiles ohne span füllen dann jeweils 25%.

embed-Tiles bilden eigene 12-Spalten-Reihen, unabhängig vom KPI-Grid.

#PWA: Dashboard als App installieren

Jedes Dashboard hat seinen eigenen PWA-Manifest unter /dashboards/manifest/<slug> mit start_url zurück zum Dashboard. Damit kann jedes Dashboard separat in Chrome/Safari als App auf den Home-Screen installiert werden — eigenes Icon (TaskMonkey), eigener Name (= Dashboard-Title).

Voraussetzungen sind erfüllt: Manifest-Link im Dashboard-Layout, Service-Worker (/sw.js) registriert, Theme-Color + apple-mobile-web-app-Tags. Chrome zeigt nach dem ersten Aufruf den „App installieren"-Button in der Adressleiste.

#Vollständiges Beispiel

'kpi' => [
    'title' => 'KPI Dashboard',
    'type' => 'kpi',
    'access' => 'token',
    'token' => '<langer Hex-String>',
    'datasource' => [
        'type' => 'google_sheet',
        'slug' => 'kpi',
        'sheetName' => 'Tabellenblatt1',
        'cache_ttl' => 20,
        'row' => 'last',
    ],
    'tiles' => [
        [
            'title' => 'Verpackt heute',
            'column' => 'Verpackt heute',
            'compare_column' => 'Verpackt gestern Vergleich',
            'format' => 'number',
            'size' => 'large',
            'span' => 3,
            'compare_label' => 'gestern um diese Zeit',
            'compare_mode' => 'higher_is_better',
        ],

        ['type' => 'row_break', 'cols' => 4],
        [
            'title' => 'Forecast heute',
            'type' => 'forecast',
            'today_column' => 'Verpackt heute',
            'yesterday_compare_column' => 'Verpackt gestern Vergleich',
            'yesterday_total_column' => 'Verpackt gestern',
        ],
        ['title' => 'Lieferbar', 'column' => 'Lieferbar'],
        ['title' => 'Gestern gesamt', 'column' => 'Verpackt gestern'],
        ['title' => 'Diese Woche', 'column' => 'Verpackt diese Woche'],

        ['type' => 'embed', 'dashboard_slug' => 'shipping_progress', 'span' => 6, 'height' => 380],
        ['type' => 'embed', 'dashboard_slug' => 'shipping_bars',     'span' => 6, 'height' => 380],
        ['type' => 'embed', 'dashboard_slug' => 'shipping_table_h',  'span' => 12, 'height' => 140],

        ['type' => 'row_break', 'cols' => 3],
        // weitere Standard-Tiles ...
    ],
],

#Tipps

• Wand-Display: access: token, cache_ttl: 20–60, große size: large, span: 3+
• Werte „NaN" oder leer: Spalten-Name passt nicht zum Sheet-Header — Groß-/Kleinschreibung zählt
• Mehrere Sub-Dashboards einbetten: in eine Reihe packen mit Spans, die zu 12 summieren
• Eigenes App-Icon pro Dashboard: aktuell wird das TaskMonkey-Icon genutzt; Custom-Icons brauchen einen eigenen manifest.json-Eintrag pro Dashboard im Workspace