Vlastní tlačítka

Vlastní tlačítka spouštějí posloupnost akcí: nastavení hodnot, výrazů a volání skriptů.

K čemu tlačítka slouží

Vlastní tlačítko (customButtons) zrychlí kroky, které jinak uživatel dělá ručně: „Schválit“ nastaví Stav na Schváleno, doplní schvalovatele a rovnou formulář uloží. Tlačítko se definuje jednou v návrháři (záložka Lišta a tlačítka) a zobrazí se v horní liště formuláře, v dolní patičce formuláře nebo jako widget na místě, které mu určíte v rozložení.

Umístění tlačítka (placement)

Od 1.19.0 se umístění nastavuje přepínacími čipy v detailu tlačítka (vlastnost placements, lze zvolit více míst najednou): Lišta formuláře (horní příkazová lišta formuláře), Patička (dolní lišta formuláře) a Ve formuláři (widget v sekci). Zapnutí čipu „Ve formuláři“ nabídne výběr sekce a vloží widget; vypnutí po potvrzení widget odebere ze všech rozvržení v jednom kroku Zpět. U volby je vidět, ve kterých sekcích tlačítko je. Patička zobrazí tlačítko i tehdy, když je zároveň widgetem. Bez zapnutého místa se tlačítko nikde nezobrazí (návrhář na to upozorní). Jak tlačítko vrátit do patičky: zapněte „Patička“ (a případně vypněte „Ve formuláři“). Karta Lišta a tlačítka ukazuje náhled lišty i patičky. Tlačítka na liště seznamu (Command Bar) a v kontextovém menu položek nejsou součástí formuláře: nastavují se v záložce Akce seznamu.

Starší vlastnost placement (legacy) se u uložených formulářů dál čte a chování zůstává stejné; platí jen, pokud placements chybí. Význam: placement určuje, kde se tlačítko zobrazí: section (výchozí, v dolní liště nebo jako widget), header (jen v horní příkazové liště) nebo both (v liště i dole). Karta tlačítka ukazuje štítek, kde se zobrazuje. Starší tlačítka bez placement se chovají jako section. Při vypnuté příkazové liště se tlačítka v záhlaví nezobrazí.

Každé tlačítko může být zobrazeno v horní liště formuláře, v dolní patičce i jako widget přímo v sekci rozložení:

V dolní liště / patičce (výchozí). Tlačítko se zobrazí vedle Uložit a Zrušit.
Jako widget v rozvržení. Zapnutí čipu Ve formuláři v detailu tlačítka (nebo vložení widgetu Vlastní tlačítko v Rozvržení, fieldType: "customButton") přidá do vybrané sekce odkaz na tlačítko přes customButtonConfig.buttonId. Tlačítko se pak zobrazí na své pozici mezi poli (a v patičce zůstane jen tehdy, je-li zapnutý i čip Patička).

Definice (popisek, akce, podmínky) je ve všech umístěních stejná. Widget navíc určuje zarovnání (alignment: left, center, right, stretch). Dolní lišta se zobrazuje, když formulář používá výchozí akce, nebo když jsou v ní vlastní tlačítka.

Karta Lišta a tlačítka: seznam a detail (od 1.28.0)

Karta Lišta a tlačítka je rozdělená na dvě části. Vlevo je seznam Tlačítka formuláře: přepínač Zobrazit horní lištu příkazů, skupina Systémová (Zpět na seznam, Upravit, Uložit, Zrušit, Tisk a Nastavení formuláře; každý řádek ukazuje režimy a má přepínač zobrazení, viz nastavení lišty) a skupina Vlastní · procesní s odkazem + Přidat tlačítko. Vlastní tlačítka lze přetáhnout za úchyt, nebo posunout šipkami u vybraného řádku; pořadí v seznamu je pořadí v liště. Štítek ϟ podmínka značí tlačítko s podmínkou zobrazení. Vpravo je detail vybraného řádku. Tlačítko Náhled lišty otevře boční panel se skutečnou lištou a patičkou (ukázková data, akce se nespouštějí); kliknutí na vlastní tlačítko ho vybere v seznamu.

Nové tlačítko přidáte odkazem + Přidat tlačítko. Detail vlastního tlačítka obsahuje Duplikovat (kopie se vloží za originál s novým ID), Smazat a karty Popisek, Ikona, Vzhled (čtyři dlaždice s ukázkou), Kde a kdy se zobrazí (umístění, režimy a podmínka) a Po kliknutí (kroky v pořadí: potvrzovací dialog, akce, validace a uložení formuláře; vypnuté kroky jsou zešedlé a bez čísla). Detail systémového tlačítka nabízí jen popisek (prázdný = výchozí text) a režimy, které určuje formulář. Vlastnosti tlačítka:

Volba	Vlastnost	Význam	Výchozí
Popisek tlačítka	`label`	text na tlačítku, může obsahovat symboly (například „✓ Schválit“). Povinný.	–
Vzhled tlačítka	`appearance`	`primary` (zvýrazněné), `secondary`, `outline` (obrysové), `subtle` (jemné)	`secondary`
Ikona	`icon`	volitelná ikona z předvoleb (stejné jako u záložek a sekcí), zobrazí se na tlačítku v liště i v sekci. Bez ní má tlačítko v liště ikonu blesku.	blesk
Zobrazit v režimech	`showInModes`	kdy je tlačítko vidět: `new`, `edit`, `display`. Musí zůstat zaškrtnutý alespoň jeden.	`new`, `edit`
Zobrazit tlačítko pouze při splnění podmínky	`condition`	jedna podmínka stejného tvaru jako v pravidlech (pole, operátor, hodnota; lze použít `$formMode`, `$userGroups` a `@Me`). Zastaralý tvar, nově se zapisuje `conditions`.	bez podmínky
Více podmínek zobrazení	`conditions`, `conditionMatch`	seznam podmínek stejného tvaru a způsob jejich spojení: `all` (platí všechny, výchozí) nebo `any` (platí alespoň jedna). Má přednost před `condition`; prázdný seznam = tlačítko je vidět vždy. V návrháři přidáte podmínky tlačítkem + Přidat podmínku a při dvou a více přepínáte platí všechny / platí alespoň jedna.	bez podmínek
Po provedení akcí rovnou validovat a uložit formulář	`submitForm`	zapnuto: po akcích se spustí uložení. Vypnuto: tlačítko jen provede akce.	zapnuto
Potvrzovací dotaz před provedením	`confirmMessage`	text dotazu zobrazený v potvrzovacím dialogu. Je-li vyplněn, tlačítko se před akcemi zeptá a při zamítnutí neprovede nic.	bez dotazu
Titulek potvrzení	`confirmTitle`	titulek potvrzovacího dialogu; je překládatelný. Bez něj se použije výchozí titulek „Potvrzení“. Dialog má tlačítka Potvrdit a Zrušit.	–

Pořadí měníte přetažením karty za úchyt vlevo, nebo šipkami u karty. Stejné pořadí platí v liště i v dolní liště.
Akce se přidávají tlačítkem + Přidat akci a provádějí se shora dolů. Tlačítko bez akcí jen odešle formulář (je-li submitForm zapnuté).
Popisek, dotaz a titulek se dají přeložit do dalších jazyků. Přepnete-li jazyk návrháře na nevýchozí, texty upravené v této kartě (popisek, titulek a dotaz potvrzení, popisky systémových tlačítek) se uloží přímo do překladů daného jazyka.

Editor vlastních tlačítek: karta tlačítka s popiskem, vzhledem, režimy, podmínkou, potvrzovacím dotazem a seznamem akcí

Hotový formulář: vlastní tlačítko „Schválit“ v dolní liště vedle Uložit a Zrušit a druhé tlačítko umístěné jako widget uvnitř sekce

Chování za běhu

Tlačítko se zobrazí, když aktuální režim formuláře je v showInModes a platí podmínky zobrazení (conditions podle conditionMatch, případně zastaralá condition). Podmínka se přehodnocuje při změně pole, na které se odkazuje.
Po kliknutí se zobrazí potvrzovací dotaz, pokud je vyplněn confirmMessage. Při zrušení se nic nestane.
Provedou se akce v pořadí. Zapsané hodnoty formulář označí za změněné, jako by je uživatel zadal.
Je-li zapnuto submitForm, formulář se zvaliduje a odešle stejně jako tlačítkem Uložit, tedy včetně pravidel onSave a skriptu onBeforeSave (viz Blokování uložení). Při chybě validace se neuloží.

Pro schvalovací tlačítko nastavte appearance: "primary", přidejte confirmMessage a podmínku, aby se zobrazilo jen ve stavu „Ke schválení“ a jen skupině schvalovatelů ($userGroups). Použijte dvě podmínky spojené jako platí všechny: Stav rovná se „Ke schválení“ a $userGroups obsahuje „Schvalovatelé“.

V režimu Display

Tlačítko s display v „Zobrazit v režimech“ je v režimu Zobrazení aktivní (i když je umístěné jako widget a pole jsou jen pro čtení). Protože Display nic neukládá, provede se jen akce callFunction (např. notifikace nebo otevření odkazu ve vaší funkci). Zápisové akce (setValue, setFieldValue, setExpression) a submitForm se přeskočí a do konzole prohlížeče se zapíše varování. Zvolili jsme přeskočení, ne skrytí, aby tlačítko s funkcí a zároveň zápisem zůstalo použitelné.

Při vypnutých skriptech

Akce callFunction je skript, a proto ji nespustí tenant, který skripty nepovolil. Taková akce se tiše přeskočí, ostatní akce (setValue, setExpression) proběhnou a případné uložení se provede. Podobně se přeskočí volání funkce, která už neexistuje.

Akce tlačítek

Každá akce má vlastnost type. V editoru jsou nabízeny tři akce: nastavení hodnoty, výpočet výrazu a volání funkce.

Nastavit hodnotu pole (starší název) `setFieldValue`

Starší název akce setValue. Chová se zcela stejně a má stejné parametry (fieldInternalName, value). Konfigurace s tímto typem dál fungují. Editor ji zobrazí jako „Nastavit hodnotu pole“ a po úpravě uloží jako setValue. Nové konfigurace používejte setValue.

{ "type": "setFieldValue", "fieldInternalName": "Stav", "value": "Schváleno" }

Nastavit pevnou hodnotu `setValue`

Zapíše pevnou hodnotu do pole. Parametry: fieldInternalName (cílové pole) a value (text, číslo nebo true/false). Editor nabízí textové políčko, hodnotu jiného typu zapište v Raw JSON. Na rozdíl od pravidla nepodporuje tokeny @Me a @Today jako hodnotu: pro ně použijte akci setExpression. Hodnota se zapíše jednorázově, uživatel ji potom může změnit.

{ "type": "setValue", "fieldInternalName": "Stav", "value": "Schváleno" }

Nastavit výraz `setExpression`

Vyhodnotí výraz a výsledek zapíše do pole. Parametry: fieldInternalName a expression. Výraz čte aktuální hodnoty formuláře v okamžiku kliknutí a funguje i při vypnutých skriptech. Prázdný výsledek pole nezmění, neplatný číselný výsledek (dělení nulou) pole vymaže. Pro doplnění aktuálního uživatele nebo dnešního data použijte @Me, @Today nebo TODAY().

{ "type": "setExpression", "fieldInternalName": "DatumSchvaleni", "expression": "@Today" }

Zavolat funkci skriptu `callFunction`

Spustí pojmenovanou funkci ze skriptů formuláře a počká na její dokončení, než pokračuje další akce. Parametr: functionName (název z scripts.functions). Funkce běží v uživatelské fázi, takže hodnoty nastavené přes ctx.setValue formulář označí za změněné. Je-li funkce neznámá nebo jsou skripty vypnuté, akce se přeskočí. Viz Při vypnutých skriptech.

{ "type": "callFunction", "functionName": "prepocitejDph" }

Příklad: schvalovací tlačítko

{
  "id": "btn-schvalit",
  "label": "✓ Schválit",
  "appearance": "primary",
  "showInModes": ["edit"],
  "condition": { "fieldInternalName": "Stav", "operator": "equals", "value": "Ke schválení" },
  "actions": [
    { "type": "setValue", "fieldInternalName": "Stav", "value": "Schváleno" },
    { "type": "setExpression", "fieldInternalName": "DatumSchvaleni", "expression": "@Today" }
  ],
  "submitForm": true,
  "confirmMessage": "Opravdu chcete žádost schválit?"
}

Stav a datum schválení se nastaví, uživatel potvrdí dotaz a formulář se uloží. Tlačítko vidí jen ten, kdo otevře položku v režimu Úpravy se stavem „Ke schválení“.

Vlastní tlačítka

K čemu tlačítka slouží

Umístění tlačítka (placement)