KPI

Ukazatel hodnoty (průběh nebo dlaždice) s barevnými prahy podle hodnoty.

Popis widgetu `kpi`

Widget KPI zobrazí hodnotu jednoho pole jako ukazatel průběhu (progress bar s procenty) nebo jako dlaždici s velkým číslem. Barva se může měnit podle hodnoty pomocí prahů: například zelená nad 80 %, oranžová nad 40 %, jinak červená. Hodí se pro plnění rozpočtu, rozpracovanost nebo počet dní do termínu. Je to virtuální widget, neukládá se do položky.

Nastavení widgetu Ukazatel / KPI dlaždice: režim zobrazení, zdrojové pole, cílová hodnota, jednotka a barevné hranice

Přidání do formuláře

Na kartě Widgety vyberte Ukazatel / KPI dlaždice a přetáhněte ho do sekce.
V inspektoru zvolte Zdrojové pole hodnoty. Nabízejí se všechna pole kromě widgetů.
Nastavte režim, cílovou hodnotu, jednotku a případně barevné hranice.

Nový widget je ukazatel průběhu s cílem 100, titulkem „Stav plnění“, jednotkou „%“ a šířkou 50 %.

Nastavení v inspektoru

Volba	Vlastnost	Význam	Výchozí
Režim zobrazení	`kpiConfig.mode`	`progress` (Progress bar %) nebo `tile` (KPI dlaždice).	`progress`
Zdrojové pole hodnoty	`kpiConfig.sourceField`	Interní název pole, z něhož se čte hodnota. Čísla se čtou i z textu (čárka jako desetinná čárka, mezery se ignorují).	nevybráno
Cílová hodnota (100 %)	`kpiConfig.targetValue`	Jen pro progress bar: hodnota, která odpovídá 100 %. Nulová nebo záporná hodnota se bere jako 100.	100
Zdroj cíle: Pevné číslo / Z jiného sloupce	`kpiConfig.targetSource`, `kpiConfig.targetField`	Jen pro progress bar. `fixed` použije číslo z `targetValue`, `field` bere cíl z hodnoty vybraného číselného sloupce a mění se živě s formulářem. Prázdný, neplatný nebo nulový cíl ve sloupci spadne na `targetValue` (případně 100), takže se nikdy nedělí nulou. Sloupec shodný se zdrojovým polem se ignoruje.	`fixed`
Nadpis karty	`kpiConfig.title`	Titulek widgetu. Když chybí, použije se vlastní popisek, potom název zdrojového pole a nakonec „Ukazatel KPI“.	prázdný
Jednotka / měna	`kpiConfig.unit`	Text za hodnotou, například `%`, `Kč`, `ks`.	prázdná
Výchozí barevný akcent	`kpiConfig.color`	`brand` (Hlavní), `success` (Zelená), `warning` (Oranžová), `danger` (Červená). Použije se, když nevyhovuje žádná hranice.	`brand`
Barevné hranice	`kpiConfig.thresholds[]`	Seznam hranic: operátor, hodnota a barva. Viz Barevné hranice.	žádné
Dle hodnoty pole / Dle % plnění	`kpiConfig.thresholdBy`	Jen u progress baru: zda se hranice porovnávají s hodnotou pole, nebo s vypočtenými procenty.	`value`
Vlastní popisek, Šířka, Viditelné	`customLabel`, `colSpan`, `defaultVisible`	Společné volby všech widgetů.	„Ukazatel KPI“, 6, ano

Další vlastnosti schématu inspektor nenabízí, nastavíte je v surovém JSON editoru:

Vlastnost	Význam
`kpiConfig.subtitle`	Podtitulek pod hodnotou, podporuje placeholdery. Když chybí, použije se popis widgetu (`description`).

Barevné hranice

Hranice se přidávají tlačítkem Přidat barevnou hranici. Každá má operátor (gte ≥, gt >, lte ≤, lt <), hodnotu a barvu. Dvě tlačítka vloží hotové sady, Semafor ↑ (vyšší = lepší) a Semafor ↓ (nižší = lepší). Tlačítko Vymazat hranice odstraní.

Vyhodnocení:

Mezi hranicemi s operátorem ≥ nebo > se vezme ta s nejvyšší splněnou hodnotou.
Když žádná z nich nevyhovuje, vezme se mezi hranicemi ≤ nebo < ta s nejnižší splněnou hodnotou.
Když nevyhovuje nic, použije se výchozí barevný akcent.

U progress baru s volbou Dle % plnění se hranice porovnávají s procenty (0 až 100). Jinak se porovnávají s hodnotou zdrojového pole (u dlaždice vždy s hodnotou).

Chování za běhu

Progress bar: titulek, procenta v barevném štítku, hodnota s jednotkou a cílem („12 / 20 ks“), pruh. Procenta se zaokrouhlují a jsou omezena na 0 až 100 %.
Dlaždice: titulek, velké číslo (barva podle hranic), jednotka a podtitulek. Barevný proužek je na levém okraji.
Číslo se formátuje podle jazyka formuláře (oddělovače tisíců, desetinná čárka). Textová hodnota, kterou nejde převést na číslo, se zobrazí jako text a pro výpočet procent se bere jako 0.
Widget reaguje živě na změnu zdrojového a cílového pole i polí v podtitulku. Ve všech režimech (Nový, Úprava, Zobrazení) se chová stejně.

Překlady textů

Přeložit lze customLabel, kpiTitle, kpiSubtitle a kpiUnit. Viz Překlady a vícejazyčnost.

Pravidla a skripty

setVisible: zobrazí nebo skryje ukazatel.
Hodnotu ukazatele ovládáte zdrojovým polem. Často je to počítané pole nebo pole naplněné akcí setExpression, například [Utraceno] / [Rozpocet] * 100.
Barvu určují hranice, pravidla ji přímo nemění.

Editor barevných hranic s předvolbou Semafor ↑ (tři řádky: operátor, hodnota, barva) a přepínač Dle hodnoty pole / Dle % plnění

Ve formuláři vedle sebe progress bar (zelený, 85 %) a KPI dlaždice (červená) se stejnými hranicemi

Příklad konfigurace (JSON)

{
  "internalName": "widget_kpi_cerpani",
  "customLabel": "Čerpání rozpočtu",
  "fieldType": "kpi",
  "colSpan": 6,
  "defaultVisible": true,
  "kpiConfig": {
    "mode": "progress",
    "sourceField": "Utraceno",
    "targetSource": "field",
    "targetField": "Rozpocet",
    "title": "Čerpání rozpočtu",
    "unit": "Kč",
    "subtitle": "Projekt [Title]",
    "color": "danger",
    "thresholdBy": "percent",
    "thresholds": [
      { "id": "t1", "operator": "lt", "value": 70, "color": "success" },
      { "id": "t2", "operator": "gte", "value": 70, "color": "warning" },
      { "id": "t3", "operator": "gte", "value": 90, "color": "danger" }
    ]
  }
}

Omezení a tipy

Zdroj je vždy jedno pole. Součty a poměry spočítejte předem v počítaném poli.
Procenta se počítají z cíle, takže u cíle 0 se použije 100. Pro metriku „čím méně, tím lépe“ použijte hranice lt a lte (předvolba Semafor ↓).
Dlaždice nezobrazuje cíl ani procenta, jen hodnotu. Chcete-li je vidět, zvolte progress bar.
Prázdné pole se zobrazí jako 0.

KPI

Popis widgetu kpi