Pravidla

Pravidla mění chování formuláře podle hodnot polí: zobrazují, zamykají, počítají a blokují uložení.

Jak pravidla fungují

Pravidlo se skládá ze spouštěče, podmínek a akcí. Pokud podmínky platí, provedou se všechny akce pravidla. Přestanou-li podmínky platit, pole se vrátí do výchozího stavu (například defaultVisible), protože se stav průběžných pravidel pokaždé přepočítá.

Shoda podmínek: všechny nebo alespoň jedna

Vlastnost matchType určuje, jak se podmínky spojují:

Pravidlo musí mít alespoň jednu podmínku a alespoň jednu akci. Výjimkou jsou pravidla se spouštěčem onLoad a onSave bez podmínek, ta platí vždy.

Skupiny podmínek

Pro složitější logiku typu (A a zároveň B) nebo (C nebo D) klikněte v bloku KDYŽ na + Skupina. Stávající podmínky se stanou první skupinou a přibude druhá. Každá skupina má vlastní volbu „platí všechny / platí alespoň jedna“, volba Mezi skupinami určuje spojení skupin (výchozí „platí alespoň jedna“, tedy NEBO). Skupinu odeberete ikonou koše; odebráním poslední podmínky skupina zmizí. Když zůstane jediná skupina, pravidlo se vrátí do jednoduchého tvaru bez ztráty podmínek. Věta „Čte se jako“ zobrazuje skupiny v závorkách.

V JSON jde o volitelné pole conditionGroups ([{ "matchType": "all", "conditions": [...] }]) a groupMatchType (all / any, výchozí any). Neprázdné conditionGroups má přednost před conditions; stará pravidla fungují beze změny jako jedna skupina.

Cíle akcí

CílZápis v targetFieldInternalNamePovolené akce
Pole nebo widgetinterní název pole, např. CenasetVisible, setRequired, setReadOnly, setValue, setExpression, blockSave (jen onSave)
Bannerinterní název widgetu BannersetVisible, setBannerIntent, setBannerTitle, setBannerContent
Záložkatab:<id záložky>setVisible, setReadOnly, setColor
Sekcesection:<id sekce>setVisible, setReadOnly, setCollapsed, setColor
Celý formulář$formblockSave
Skripty$scriptcallFunction

Editor nabídne jen akce, které se pro vybraný cíl hodí. Při změně cíle převede stávající akci na nejbližší povolenou. Pravidlo uložené s nepovolenou kombinací (například setCollapsed na pole) odmítne kontrola konfigurace.

Dědičnost záložek a sekcí

Skrytí nebo zamčení záložky či sekce se přenáší na všechna pole uvnitř:

Záložky i sekce mají také vlastní viditelnostní podmínky a barvu podle hodnoty pole. Ty se nastavují v rozložení (viz Rozložení), ne v pravidlech, a vyhodnocují se před pravidly.

Tokeny @Me a @Today

Režim formuláře

V režimu zobrazení (display) jsou všechna pole jen pro čtení a nepovinná bez ohledu na pravidla. Pravidla se vyhodnocují dál, takže skrývání a barvy fungují. Hodnoty, které pravidla nebo skripty nastaví v režimu zobrazení, formulář nikdy neoznačí za změněný. Chcete-li pravidlo omezit na režim, přidejte podmínku na $formMode.

Pořadí vyhodnocení

  1. Pro každé pole, sekci a záložku se vezme výchozí stav z rozložení (defaultVisible, defaultRequired, defaultReadOnly, viditelnostní podmínky, barva podle pole).
  2. Pravidla s trigerem always se projdou v pořadí seznamu (číslo vlevo od názvu). Akce uvnitř pravidla se provádějí shora dolů. Když více pravidel nastaví stejnou vlastnost stejného cíle, vyhrává to, které je v seznamu později.
  3. Skrytí a zamčení záložek a sekcí se propíše do polí uvnitř (dědičnost).
  4. V režimu zobrazení se všechna pole zamknou a zruší se povinnost.
  5. Jednorázová pravidla onLoad se vyhodnotí po načtení formuláře a pravidla onSave při uložení. Jejich změny stavu (viditelnost, povinnost, zamčení) přepíšou stav z průběžných pravidel a skript přes ctx je může později změnit.

Pravidla čtou jen pole, která jsou použitá v jejich podmínkách a výrazech. Psaní do nesouvisejících polí proto pravidla zbytečně nepřepočítává.

Editor pravidel

Otevřete návrháře, záložku Pravidla. Vlevo je seznam, vpravo detail vybraného pravidla.

Editor pravidel: seznam vlevo, detail vybraného pravidla vpravo s bloky KDYŽ a PAK a větou „Čte se jako“

Věta „Čte se jako“

Pod hlavičkou pravidla se skládá věta v přirozeném jazyce, například „Při změně hodnoty, když Stav je rovno Schváleno, pak uzamkni Cena“. Slouží ke kontrole, že pravidlo dělá to, co zamýšlíte. Větu vytváří editor z nastavení pravidla, upravit ji nelze. Jazyk věty odpovídá jazyku návrháře.

Zapnutí a vypnutí pravidla

Přepínač u pravidla v seznamu nastaví enabled. Vypnuté pravidlo (enabled: false) zůstane v konfiguraci, ale nevyhodnocuje se, takže je ideální pro dočasné odstavení. Chybějící hodnota znamená zapnuto, starší konfigurace tedy fungují beze změny.

Nevalidní pravidla

Pokud smažete pole, záložku nebo sekci, na které pravidlo odkazuje, pravidlo se nesmaže. Návrhář mu zapíše invalidReason se seznamem chybějících cílů a zobrazí ho se štítkem Nevalidní a červeným upozorněním s výčtem toho, co chybí. Za běhu se takové pravidlo přeskakuje a nezpůsobí chybu.

Nevalidní pravidlo: štítek „Nevalidní“ v seznamu a červený pruh s výčtem chybějících polí v detailu (nejdřív smažte pole, které pravidlo používá)

Dialog dopadu při mazání

Než smažete pole, sekci, záložku nebo pravidlo, návrhář ukáže dialog dopadu: kolik polí se odebere, která pravidla se stanou nevalidními (zůstanou zachována, ale nebudou se vyhodnocovat) a které skripty na odebíraná pole odkazují (ty se automaticky neupraví). Potvrdíte tlačítkem Smazat, nebo smazání zrušíte. Změnu lze vrátit tlačítkem Zpět, dokud návrháře nezavřete.

Dialog „Odebrat pole“ se seznamem pravidel, která se po odebrání stanou nevalidní (vytvořte pravidlo na pole a zkuste pole odebrat v rozložení)

Limit pravidel ve verzi Free

Verze Community (Free) počítá s 3 pravidly. Při větším počtu návrhář zobrazí žlutý pruh „běží X z Y pravidel“, u pravidel nad limit štítek Neaktivní · limit, jejich přepínač je zamčený a v liště varování se objeví upozornění. Pravidla se uloží i nad limit. Licence Pro limit odstraňuje, viz Licencování.

Seznam s více než třemi pravidly ve verzi Free: pruh s limitem a štítek „Neaktivní · limit“ u čtvrtého pravidla

Spouštěče pravidel

Spouštěč (trigger) se vybírá v hlavičce pravidla. Chybí-li, platí always.

Vždy (always)

V editoru „Při změně hodnoty“. Výchozí spouštěč. Pravidlo se vyhodnotí po načtení formuláře a znovu při každé změně pole použitého v jeho podmínkách (nebo v režimu formuláře). Hodí se pro živou logiku: zobrazit pole podle stavu, zamknout, vypočítat hodnotu, změnit text banneru.

Při načtení (onLoad)

V editoru „Po načtení formuláře“. Pravidlo se vyhodnotí jednou po načtení formuláře (a znovu při změně režimu formuláře nebo konfigurace pravidel). Hodí se pro výchozí stav, který pak může uživatel změnit: sbalit sekce, předvyplnit hodnotu, zobrazit uvítací banner, zavolat inicializační funkci.

Hodnota nastavená pravidlem onLoad (setValue, setExpression) formulář neoznačí za změněný, takže samotné otevření nevyvolá dotaz na neuložené změny. V režimu Úpravy se ale při uložení zapíše do SharePointu, pokud se liší od uložené hodnoty. Uloží se jen tehdy, když uživatel formulář uloží; zavřením bez uložení se nic nezmění.

Při uložení (onSave)

V editoru „Při uložení formuláře“. Pravidlo se vyhodnotí při stisku Uložit, po úspěšné validaci polí a před skriptem onBeforeSave. Hodí se pro kontroly, které se nevejdou do validace pole, a pro hodnoty zapsané až při uložení (razítko data, přiřazení uživatele).

Operátory podmínek

Podmínka má tvar { "fieldInternalName", "operator", "value" }. Hodnota value se u operátorů isEmpty a isNotEmpty nepoužívá. Složité typy polí se porovnávají podle svých viditelných částí:

Rovná se equals

Platí, když se hodnota pole shoduje s value. Texty se porovnávají bez rozlišení velikosti písmen a bez okrajových mezer, čísla číselně ("10" se rovná 10), ano/ne jako true/false. U vícehodnotových polí a osob stačí shoda s kteroukoli hodnotou. Prázdné pole se nerovná žádné hodnotě; pro prázdnost použijte isEmpty.

{ "fieldInternalName": "Status", "operator": "equals", "value": "Schváleno" }

Nerovná se notEquals

Opak operátoru equals. Prázdné pole se nerovná zadané hodnotě, takže podmínka platí. U vícehodnotových polí platí, když se žádná hodnota neshoduje.

{ "fieldInternalName": "Status", "operator": "notEquals", "value": "Koncept" }

Obsahuje contains

Platí, když text hodnoty obsahuje zadaný řetězec (bez rozlišení velikosti písmen). U vícehodnotových polí a osob stačí, aby řetězec obsahovala kterákoli hodnota. Prázdné pole podmínku nesplňuje. Pro skupiny ($userGroups) funguje jako test členství.

{ "fieldInternalName": "Title", "operator": "contains", "value": "faktura" }

Neobsahuje notContains

Opak operátoru contains. Prázdné pole podmínku splňuje.

{ "fieldInternalName": "Title", "operator": "notContains", "value": "storno" }

Je větší než greaterThan

Porovnává čísla a data. Čísla se zapisují s tečkou (3.14, záporná -5), data ve tvaru YYYY-MM-DD nebo YYYY-MM-DDTHH:mm v místním čase. U opakující se tabulky a vícehodnotových polí se porovnává počet položek. Pokud kterákoli strana není číslo ani datum (včetně prázdného pole), podmínka neplatí.

{ "fieldInternalName": "Cena", "operator": "greaterThan", "value": 10000 }

Je menší než lessThan

Stejné jako greaterThan, jen opačným směrem. Prázdné pole podmínku nesplňuje (není to nula).

{ "fieldInternalName": "Termin", "operator": "lessThan", "value": "2026-12-31" }

Je prázdné isEmpty

Platí pro hodnotu null, prázdný text nebo text jen z mezer, prázdný seznam, prázdnou opakující se tabulku, osobu, vyhledávání či termín bez vybrané hodnoty a přílohy bez souborů. Nepotřebuje value.

{ "fieldInternalName": "Poznamka", "operator": "isEmpty" }

Není prázdné isNotEmpty

Opak operátoru isEmpty. Hodí se pro „je-li vyplněno X, ukaž Y“.

{ "fieldInternalName": "Schvalovatel", "operator": "isNotEmpty" }

Akce pravidel

Každá akce má cíl (targetFieldInternalName), typ (action) a hodnotu (value). Akce se provádějí v pořadí, v jakém jsou uvedeny.

Zobrazit / skrýt setVisible

Hodnota true pole zobrazí, false skryje. Cílem může být pole, banner, záložka (tab:id) nebo sekce (section:id). Skryté pole se nevaliduje. Skrytím záložky nebo sekce se skryje i vše uvnitř (dědičnost).

{ "targetFieldInternalName": "section:sec_schvaleni", "action": "setVisible", "value": false }

Nastavit povinnost setRequired

Hodnota true pole učiní povinným, false nepovinným. Cílem je pole (ne záložka ani sekce). V režimu zobrazení se povinnost ruší vždy. Povinnost se vyhodnocuje při uložení, skryté a zamčené pole chybu nehlásí.

{ "targetFieldInternalName": "DuvodZamitnuti", "action": "setRequired", "value": true }

Nastavit jen pro čtení setReadOnly

Hodnota true pole zamkne, false odemkne. Cílem může být pole, záložka nebo sekce; zamčení kontejneru zamkne všechna pole uvnitř.

V Úpravách a Novém zůstane zamčené pole plně čitelné: nevypadá jako zašedlý zakázaný vstup, ale jako zamčené pole s jemně odlišeným pozadím a rámečkem a běžnou barvou textu. Text, číslo a víceřádkový text jsou vstupy jen pro čtení (text lze označit a zkopírovat), ostatní typy (výběr, datum, Ano/Ne, osoba, vyhledávání, taxonomie, hodnocení, umístění a vypočítané pole) ukážou hodnotu v zamčeném rámečku. Čtečka obrazovky pole ohlásí jako jen pro čtení. Hodnota zůstává ve formuláři beze změny, uloží se tak, jak byla, a zamčení samo formulář neoznačí za změněný.

{ "targetFieldInternalName": "tab:tab_cena", "action": "setReadOnly", "value": true }

Sbalit / rozbalit sekci setCollapsed

Hodnota true sekci sbalí, false rozbalí. Cíl musí být sekce (section:id), účinek má u sekce nastavené jako sbalitelná. Uživatel ji může potom ručně přepnout. Při neúspěšné validaci se sekce s chybou rozbalí sama.

{ "targetFieldInternalName": "section:sec_prilohy", "action": "setCollapsed", "value": true }

Nastavit hodnotu setValue

Zapíše pevnou hodnotu do pole. Hodnota může být text, číslo, true/false, prázdný text (vymaže pole), objekt pro složitější typy, nebo token @Me (aktuální uživatel) či @Today (dnešní datum). Cílem je pole.

{ "targetFieldInternalName": "Zadavatel", "action": "setValue", "value": "@Me" }

Zavolat funkci skriptu callFunction

Spustí pojmenovanou funkci ze skriptů formuláře. Cíl je vždy $script, hodnota je název funkce (musí existovat v scripts.functions, jinak kontrola konfigurace selže). Funkce dostane objekt ctx.

{ "targetFieldInternalName": "$script", "action": "callFunction", "value": "prepocitejDph" }

Nastavit výraz setExpression

Vypočítá hodnotu pole ze vzorce nad jinými poli, například [Cena] * [Kusy]. Syntaxe, funkce a chování jsou na stránce Výrazy a funkce. Výraz @Me dosadí aktuálního uživatele jako u setValue. Chování zápisu je stejné jako u setValue (vynucená hodnota, ochrana proti smyčce). Výraz, který nelze přeložit jako vzorec, se použije jako textová šablona. Neplatný číselný výsledek (dělení nulou) pole vymaže.

{ "targetFieldInternalName": "Celkem", "action": "setExpression", "value": "ROUND([Cena] * [Kusy] * 1.21, 2)" }

Zablokovat uložení blockSave

Zastaví uložení a zobrazí hlášku. Použitelná jen v pravidlech se spouštěčem onSave. Cílem je buď $form (chyba celého formuláře), nebo pole (hláška se zobrazí u pole a formulář na něj přeskočí, případně rozbalí sekci a přepne záložku). Hodnotou je text hlášky, nesmí být prázdný. Více blokujících pravidel zobrazí všechny hlášky najednou v horním panelu.

{
  "id": "rule-kontrola-ceny",
  "name": "Cena musí být kladná",
  "trigger": "onSave",
  "matchType": "all",
  "conditions": [{ "fieldInternalName": "Cena", "operator": "lessThan", "value": 1 }],
  "actions": [{ "targetFieldInternalName": "Cena", "action": "blockSave", "value": "Cena musí být větší než 0." }]
}

Zobrazit upozornění showNotification

Zobrazí nad formulářem nezávazné upozornění (lišta s tlačítkem Rozumím), vyplňování neblokuje. Jen pro spouštěč always. Spustí se ve chvíli, kdy se podmínky pravidla po změně uživatelem začnou plnit (nesplněno → splněno), nikdy při načtení formuláře a během trvajícího splnění se neopakuje. Hodnota je text upozornění (tokeny {Pole}), volitelně title a severity (info, warning – výchozí, error, success). Cílem je $form. Texty lze přeložit v záložce Překlady.

{ "targetFieldInternalName": "$form", "action": "showNotification", "value": "Nad 500 000 Kč je nutné schválení CFO.", "severity": "warning" }

Potvrdit změnu s návratem confirmChange

Když se podmínky po změně uživatelem začnou plnit, otevře modální dialog s tlačítky Pokračovat a Zrušit změnu (vlastní texty confirmLabel / cancelLabel, volitelný title). Pokračovat změnu ponechá. Zrušit změnu (i zavření dialogu) vrátí cílové pole na hodnotu před změnou; návrat dialog znovu nespustí. Cílem je pole, které se vrací (obvykle pole z podmínky). Jen pro spouštěč always, nikdy při načtení formuláře. Více dialogů se zobrazí postupně.

{
  "id": "rule-storno",
  "name": "Potvrzení storna",
  "trigger": "always",
  "matchType": "all",
  "conditions": [{ "fieldInternalName": "Stav", "operator": "equals", "value": "Stornováno" }],
  "actions": [{ "targetFieldInternalName": "Stav", "action": "confirmChange", "value": "Opravdu stornovat {Title}?", "cancelLabel": "Ponechat původní stav" }]
}

Změnit typ banneru setBannerIntent

Přepne barvu a ikonu widgetu Banner. Hodnota je info, warning, error nebo success.

{ "targetFieldInternalName": "widget_banner_1", "action": "setBannerIntent", "value": "warning" }

Změnit titulek banneru setBannerTitle

Nahradí titulek banneru. Text může obsahovat tokeny [Pole] nebo {Pole} (hodnota pole), @Me a @Today. Dosazuje se čistý text, nikdy se nic nevyhodnocuje jako vzorec.

{ "targetFieldInternalName": "widget_banner_1", "action": "setBannerTitle", "value": "Žádost {Title}" }

Změnit text banneru setBannerContent

Nahradí obsah banneru, stejně jako setBannerTitle s podporou tokenů.

{ "targetFieldInternalName": "widget_banner_1", "action": "setBannerContent", "value": "Částka [Cena] Kč čeká na schválení od @Me." }

Nastavit barvu záložky nebo sekce setColor

Přebarví záložku (tab:id) nebo sekci (section:id). Hodnota je klíč přednastavené barvy, hex barva #rrggbb, nebo none (bez barvy). Na pole se akce nedá použít.

{ "targetFieldInternalName": "section:sec_stav", "action": "setColor", "value": "#d13438" }

Blokování uložení a životní cyklus

Při stisku Uložit se provedou kroky v tomto pořadí:

  1. Validace polí (povinnost, formát). Chyby jsou u polí.
  2. Pravidla onSave. Pokud nějaké blockSave platí, uložení se zastaví, hlášky se zobrazí u polí a v horním panelu.
  3. Zápis hodnot z setValue a setExpression pravidel onSave a callFunction těchto pravidel.
  4. Skript onBeforeSave: vrátí-li text nebo false, uložení se zastaví (viz Skripty).
  5. Odeslání do SharePointu.

blockSave funguje i při vypnutých skriptech. Pro validaci, která musí platit vždy, ji volte před onBeforeSave.

Ladění pravidel

Když pravidlo nedělá, co čekáte, zapněte ladicí režim. Přidejte k adrese formuláře ?fcdebug=1 (platí jen pro tuto stránku a nemění uloženou konfiguraci), nebo zapněte nastavení debugMode. V konzole prohlížeče (F12) pak uvidíte výpisy s předponou [FC debug]:

Konzole prohlížeče s výpisem [FC debug]: rozbalená skupina vyhodnocení pravidel s podmínkami a výsledky (otevřete formulář s parametrem ?fcdebug=1)

Časté příčiny „pravidlo nefunguje“: pravidlo je vypnuté nebo nevalidní, spouštěč je onLoad místo always, hodnota v podmínce má jiný tvar než v poli (například jméno místo ID), nebo další pravidlo níže v seznamu stejnou vlastnost přepsalo.