Editační formulář - ActionButtons

1. Základní informace

1.1. Popis ovládacího prvku

Každý editační formulář automaticky obsahuje ovládací prvek „ActionButtons“, který se skládá ze třech základních tlačítek potřebných pro práci s formulářem – „Uložit“, „Smazat“ a „Zpět“.

2. Seznam záložek v dialogu nastavení ovládacího prvku

• Obecné – Nastavení obecných vlastností
• Uložit – Nastavení tlačítka „Uložit“
• Smazat – Nastavení tlačítka „Smazat“
• Zpět – Nastavení tlačítka „Zpět“
• Pod skriptem každé události („OnAfterOpen“, „OnBeforeSave“, „OnAfterSave“, „OnBeforeOpen“, „OnBeforeDelete“, „OnAfterDelete“) je zaškrtávací pole „Zakázat skript“. Jeho zaškrtnutím se spouštění skriptu vypne, ať je událost vyvolána v editačním formuláři, nebo jinak (například hromadnou změnou v nahlížecí tabulce); skript zůstává uložený.

2.1. Záložka „Obecné“

2.1.1. Možnosti

• Skrýt tlačítko „Uložit“
  • Zaškrtnutí tohoto pole určuje, zda má být v editačním formuláři skryté tlačítko „Uložit“.
  • Skrytí tlačítka není zabezpečením proti změně záznamu – záznam lze dál uložit tlačítky „Uložit a nový“, „Uložit a pokračovat v editaci“, tlačítkem „Button“ typu „Otevřít nahlížecí stránku“ nebo „Skript“ se zaškrtnutým krokem „1. Uložit záznam“ nebo „3. Uložit záznam“, tlačítkem „Button“ typu „Otevřít editační formulář“ se zaškrtnutým krokem „1. Uložit záznam“ a tlačítkem „Button“, jehož skript záznam uloží (krokem „3. Uložit záznam“ nebo funkcí „SCHEDULESAVE“). Vynucené uložení tlačítka typu „Tisk do šablony“ a „Otevřít editační formulář“ bez skriptu záznam uloží také; přeskočí se jen ve formuláři pouze pro čtení, jak popisuje samostatná příručka Editační formulář – Button. Kdo smí záznam měnit, určují „Práva na editaci“ editačního formuláře.
• Skrýt tlačítko „Smazat“
  • Zaškrtnutí tohoto pole určuje, zda má být v editačním formuláři skryté tlačítko „Smazat“.
  • Na rozdíl od tlačítka „Uložit“ skrytí zakáže smazání záznamu v editačním formuláři i na straně serveru a hromadné mazání záznamů v nahlížecí tabulce pak zůstane dostupné jen administrátorovi. Smazání záznamu příkazem skriptu tím zakázané není.
• Skrýt tlačítko „Zpět“
  • Zaškrtnutí tohoto pole určuje, zda má být v editačním formuláři skryté tlačítko „Zpět“.
• Zobrazit tlačítko „Uložit a pokračovat v editaci“
  • Zaškrtnutí tohoto pole určuje, zda má být v editačním formuláři zobrazené tlačítko „Uložit a pokračovat v editaci“.
• Zobrazit tlačítko „Uložit a nový“
  • Zaškrtnutí tohoto pole určuje, zda má být v editačním formuláři zobrazené tlačítko „Uložit a nový“.
  • Text tlačítka může být nastaven na vlastní. Vlastní text smí obsahovat proměnné (hodnotu ovládacího prvku formuláře zápisem #ng_...:value#) a serverové funkce, které se vyhodnotí při zobrazení formuláře; je-li výsledek prázdný, tlačítko se nezobrazí. Skrytí tlačítka není zabezpečení – práva k záznamu se při uložení ověřují vždy.

2.1.2. OnAfterOpen

• Skript, který se provede po otevření záznamu v editačním formuláři.
• Skript se spustí jen při načtení editačního formuláře. Po odeslání formuláře – například po stisknutí tlačítka nebo po neúspěšném uložení – se znovu nespustí. Načte-li se formulář znovu přesměrováním – po uložení tlačítkem „Uložit a pokračovat v editaci“ nebo po navigaci funkcí „SCHEDULEFORM“ na tentýž záznam –, skript se spustí znovu.
• V uživatelském režimu se skript nespustí, nezobrazí-li se uživateli žádný ovládací prvek formuláře (například nemá-li právo k žádnému z nich). Výchozí hodnoty ovládacích prvků se v takovém případě při otevření také nevyplní.
• Databázové změny provedené tímto skriptem se potvrdí ihned po jeho dokončení v samostatné databázové transakci.
• Chyba skriptu nezabrání otevření formuláře: editační formulář se otevře s chybovým hlášením a databázové změny skriptu, které skript dosud nepotvrdil funkcí „COMMIT()“, se vrátí zpět. Hodnoty, které skript před chybou přiřadil do ovládacích prvků, ve formuláři zůstanou. Sloupce, které skript před chybou naplánoval k uložení funkcí „SCHEDULESAVE“ s parametrem, se u uloženého záznamu přesto zapíší do databáze, a to s hodnotami přiřazenými před chybou.
• Serverová funkce „SCHEDULESAVE()“ bez parametru v tomto skriptu uloží záznam hned při otevření, a to celým ukládacím procesem včetně validace a skriptů „OnBeforeSave“ a „OnAfterSave“. Nový záznam se tím založí. Záznam se uloží i ve formuláři pouze pro čtení, a to s hodnotami uloženými v databázi a s hodnotami, které nastaví skript; odmítne se jen u záznamu zamčeného jiným uživatelem, a to hlášením o uzamčení záznamu.
• Navigace naplánovaná v tomto skriptu (SCHEDULEBACK, SCHEDULEFORM, SCHEDULEVIEWPAGE, SCHEDULEURL, SCHEDULEPORTLETS a další) a funkce „HIDEFORM“ se provedou jen v uživatelském režimu. Funkce „SCHEDULEFORM“ na právě otevřený záznam se ignoruje a funkce „SCHEDULEMAILMESSAGE“ v tomto skriptu nemá účinek.

2.2. Záložka „Uložit“

2.2.1. JavaScript

• Volání funkce (nebo jiný javascriptový výraz) bez středníku na konci, například „beforeSave()“, které se vyhodnotí po stisknutí tlačítka „Uložit“. Výsledek se použije jako podmínka, proto se funkce zapisuje i se závorkami – samotný název funkce bez závorek funkci nezavolá. Identifikátory „#ng_...#“ se ve výrazu nahradí stejně jako v ostatním JavaScriptu editačního formuláře.
• Výraz smí mít nejvýše 50 znaků. Delší logiku je nutné umístit do funkce v ovládacím prvku „JavaScript“ editačního formuláře a do pole zapsat jen její volání.
• Je-li návratová hodnota funkce hodnota „true“, dojde ke spuštění serverového skriptu „OnBeforeSave“.
• Je-li návratová hodnota funkce nepravdivá – „false“, ale také „0“, „null“, prázdný text nebo „undefined“, kterou vrací funkce bez příkazu „return“ –, nedojde ke spuštění serverového skriptu „OnBeforeSave“, a nedojde k uložení záznamu.
• Výraz se vyhodnotí i před uložením záznamu tlačítky „Uložit a nový“, „Uložit a pokračovat v editaci“ a „Synchronizovat“, před automatickým uložením záznamu (například při zakládání nebo otevírání vnořeného záznamu z nahlížecí tabulky formuláře) a po stisknutí tlačítka „Button“ typu „Otevřít editační formulář“ nebo „Tisk do šablony“, u typů „Otevřít nahlížecí stránku“ a „Skript“ jen se zaškrtnutým krokem „1. Uložit záznam“ nebo „3. Uložit záznam“. U tlačítka „Button“ se výraz vyhodnotí za kódem z pole „Klient“, a to jen tehdy, nevrátí-li tento kód hodnotu příkazem „return“ dřív.

2.2.2. OnBeforeSave

• Skript, který se provede před uložením záznamu do databáze.
• Validace ovládacích prvků proběhne ještě před spuštěním tohoto skriptu. Povinné pole proto nelze doplnit hodnotou až v tomto skriptu – validace ho vyhodnotí jako nevyplněné.
• Skript „OnBeforeSave“ a vlastní uložení záznamu probíhají v jedné databázové transakci. Chyba skriptu zabrání uložení záznamu a vrátí zpět také databázové změny provedené tímto skriptem, které skript dosud nepotvrdil funkcí „COMMIT()“. Detailní popis změn, které chyba skriptu nevrátí, je uveden v samostatné příručce Návrhář skriptů.
• Funkce „SKIPSAVE()“ se chová jinak než chyba: přeskočí pouze vlastní uložení záznamu, databázové změny provedené skriptem se potvrdí a následně se spustí „OnAfterSave“.
• Spustí-li se skript „OnBeforeSave“ jinak než uložením editačního formuláře – například hromadnou změnou nebo změnou hodnoty přímo v nahlížecí tabulce, v panelu detailů nahlížecí tabulky, na kartě prvku Kanban nebo v detailech prvku Tree, importem z Excelu nebo serverovou funkcí „OBSOAS“ – funkce „SKIPSAVE()“ změny zapsané příkazy skriptu („Uložit hodnotu do databáze“, „Nový záznam“, „Smazat záznam“ a další zapisující příkazy) neprovede. Provedou se jen ty z nich, které skript potvrdil funkcí „COMMIT()“. Transakce skriptu se ale na rozdíl od chyby potvrdí: zápisy externích funkcí prostřednictvím předaného objektu „cmd“ zůstanou a e-maily zařazené k odeslání příkazem „Odeslat e-mail“ se odešlou.
• Při hromadné změně hodnoty z nahlížecí tabulky chyba skriptu u jednotlivého záznamu zpracování nepřeruší – záznam se nezmění a zpracování pokračuje dalším záznamem. Po dokončení se uživateli zobrazí text první chyby a počet záznamů, u kterých skript selhal.
• Navigace naplánovaná v tomto skriptu (SCHEDULEBACK, SCHEDULEFORM, SCHEDULEVIEWPAGE, SCHEDULEURL, SCHEDULEPORTLETS a další) se provede až po uložení záznamu, a to jen tlačítkem „Uložit“, „Uložit a nový“, „Uložit a pokračovat v editaci“ nebo „Synchronizovat“. Skript „OnAfterSave“ ji převezme a může ji změnit. Uloží-li se záznam jinak – krokem tlačítka „Button“ nebo funkcí „form_Save“ – nebo spustí-li se skript jinak než uložením editačního formuláře, navigace se neprovede; u tlačítka „Button“ o přesměrování rozhoduje jeho vlastní skript.

2.2.3. OnAfterSave

• Skript, který se provede po uložení záznamu do databáze.
• Spustí se pouze po úspěšném potvrzení transakce, která obsahuje skript „OnBeforeSave“ a vlastní uložení záznamu.
• Skript „OnAfterSave“ běží v nové databázové transakci. Jeho chyba vrátí zpět databázové změny provedené tímto skriptem, které skript dosud nepotvrdil funkcí „COMMIT()“, ale již uložený záznam neobnoví do původního stavu.
• Přiřazení hodnoty do ovládacího prvku aktuálního záznamu (příkaz „Přiřadit hodnotu“) se v tomto skriptu do databáze neuloží, protože záznam je již uložený. Hodnotu aktuálního záznamu je nutné zapsat příkazem „Uložit hodnotu do databáze“.
• Navigace naplánovaná v tomto skriptu se provede jen po uložení tlačítkem „Uložit“, „Uložit a nový“, „Uložit a pokračovat v editaci“ nebo „Synchronizovat“, stejně jako navigace převzatá ze skriptu „OnBeforeSave“.

2.2.4. OnBeforeOpen

• Skript, který se provede před otevřením nového záznamu v editačním formuláři.
• Skript „OnBeforeOpen“ se provede po stisknutí tlačítka „Uložit a nový“ v editačním formuláři.
• Skript běží nad právě uloženým záznamem – proměnná „#id#“ i hodnoty ovládacích prvků patří uloženému záznamu, ne novému.
• Přiřazení hodnoty do ovládacího prvku se neuloží, a to ani se serverovou funkcí „SCHEDULESAVE“; do uloženého záznamu se zapíší jen přepočtené hodnoty prvků „AutoSum“.
• Hodnoty pro nový záznam lze předat serverovými funkcemi „SCHEDULEDEFAULTVALUE“ a „SCHEDULEDEFAULTVALUES“. Rodičovský záznam nového záznamu (identifikátory „pid“ a „pform“) jimi v tomto skriptu nastavit nelze – nový záznam převezme rodičovský záznam právě uloženého záznamu.
• Skončí-li skript chybou, nový záznam se neotevře.
• Navigace naplánovaná v tomto skriptu (SCHEDULEFORM, SCHEDULEURL a další) se neprovede.
• Naplánuje-li navigaci skript „OnBeforeSave“ nebo „OnAfterSave“ ukládaného záznamu, provede se po stisknutí tlačítka „Uložit a nový“ tato navigace; skript „OnBeforeOpen“ se pak nespustí a nový záznam se neotevře.

2.3. Záložka „Smazat“

2.3.1. JavaScript

• Volání funkce (nebo jiný javascriptový výraz) bez středníku na konci, například „beforeDelete()“, které se vyhodnotí po stisknutí tlačítka „Smazat“. Samotný název funkce bez závorek funkci nezavolá.
• Výraz smí mít nejvýše 250 znaků. Delší logiku je nutné umístit do funkce v ovládacím prvku „JavaScript“ editačního formuláře a do pole zapsat jen její volání.
• Je-li návratová hodnota funkce hodnota „true“, dojde ke spuštění serverového skriptu „OnBeforeDelete“.
• Je-li návratová hodnota funkce nepravdivá – „false“, ale také „0“, „null“, prázdný text nebo „undefined“, kterou vrací funkce bez příkazu „return“ –, nedojde ke spuštění serverového skriptu „OnBeforeDelete“, a nedojde ke smazání záznamu.
• Je-li funkce vyplněna, nahradí výchozí dotaz na potvrzení smazání záznamu – výchozí dotaz se pak nezobrazí.

2.3.2. Možnosti

• Vždy povolit mazání vlastníkovi nebo spoluvlastníkovi záznamu
  • Zaškrtnutí tohoto pole určuje, zda má být povoleno mazání záznamu vlastníkovi nebo spoluvlastníkovi záznamu bez ohledu na existenci dalších ovládacích prvků ve formuláři, na které vlastník nebo spoluvlastník záznamu nemá právo.

2.3.3. OnBeforeDelete

• Skript, který se provede před smazáním záznamu z databáze.
• Skript „OnBeforeDelete“ a vlastní smazání záznamu probíhají v jedné databázové transakci. Chyba skriptu zabrání smazání záznamu a vrátí zpět také databázové změny provedené tímto skriptem, které skript dosud nepotvrdil funkcí „COMMIT()“. Detailní popis změn, které chyba skriptu nevrátí, je uveden v samostatné příručce Návrhář skriptů.
• Funkce „SKIPDELETE()“ se chová jinak než chyba: přeskočí vlastní smazání záznamu a následně se spustí „OnAfterDelete“. Změny zapsané příkazy skriptu („Uložit hodnotu do databáze“, „Nový záznam“, „Smazat záznam“ a další zapisující příkazy) se přitom neprovedou; provedou se jen ty z nich, které skript potvrdil funkcí „COMMIT()“. Transakce skriptu se přitom potvrdí, takže zápisy externích funkcí prostřednictvím předaného objektu „cmd“ zůstanou.
• Při hromadném mazání záznamů z nahlížecí tabulky chyba skriptu u jednotlivého záznamu zpracování nepřeruší – záznam se nesmaže a zpracování pokračuje dalším záznamem. Po dokončení se uživateli zobrazí text první chyby a počet záznamů, u kterých skript selhal.
• Navigace naplánovaná v tomto skriptu (SCHEDULEBACK, SCHEDULEFORM, SCHEDULEVIEWPAGE, SCHEDULEURL, SCHEDULEPORTLETS a další) se provede až po smazání záznamu. Skript „OnAfterDelete“ ji převezme a může ji změnit. Při hromadném mazání záznamů z nahlížecí tabulky se navigace neprovede. Byl-li záznam smazán, založí funkce „SCHEDULEFORM“ nový záznam jako vnořený záznam rodičovského záznamu smazaného záznamu (neurčí-li jiný rodičovský záznam funkce „SCHEDULEDEFAULTVALUE“ nebo nemá-li parametr „back“ hodnotu „true“) a smazaný záznam se nepoužije ani jako cíl návratu; funkce „SCHEDULEMAILMESSAGE“ na smazaný záznam neodkáže.

2.3.4. OnAfterDelete

• Skript, který se provede po smazání záznamu z databáze.
• Spustí se pouze po úspěšném potvrzení transakce, která obsahuje skript „OnBeforeDelete“ a vlastní smazání záznamu.
• Skript „OnAfterDelete“ běží v nové databázové transakci. Jeho chyba vrátí zpět databázové změny provedené tímto skriptem, které skript dosud nepotvrdil funkcí „COMMIT()“, ale již smazaný záznam neobnoví.
• Navigace naplánovaná v tomto skriptu se provede po smazání záznamu, stejně jako navigace převzatá ze skriptu „OnBeforeDelete“; při hromadném mazání záznamů z nahlížecí tabulky se neprovede. Byl-li záznam smazán, platí pro funkce „SCHEDULEFORM“ a „SCHEDULEMAILMESSAGE“ totéž co ve skriptu „OnBeforeDelete“.
• Skončí-li skript chybou v editačním formuláři, navigace naplánovaná před chybou se přesto provede, stejně jako skripty naplánované před chybou funkcí „SCHEDULESCRIPT“. Při hromadném mazání záznamů z nahlížecí tabulky se naplánované skripty po chybě neprovedou.

2.4. Záložka „Zpět“

2.4.1. JavaScript

• Volání funkce (nebo jiný javascriptový výraz) bez středníku na konci, například „beforeBack()“, které se vyhodnotí po stisknutí tlačítka „Zpět“. Samotný název funkce bez závorek funkci nezavolá.
• Výraz smí mít nejvýše 50 znaků. Delší logiku je nutné umístit do funkce v ovládacím prvku „JavaScript“ editačního formuláře a do pole zapsat jen její volání.
• Je-li návratová hodnota funkce hodnota „true“, dojde k přesměrování uživatele zpět na místo, odkud byl editační formulář s aktuálně otevřeným záznamem vyvolán. Obsahuje-li formulář neuložené změny, vyhodnotí se výraz ještě před dotazem na opuštění formuláře; po potvrzení dotazu se znovu nevyhodnocuje.
• Je-li návratová hodnota funkce nepravdivá – „false“, ale také „0“, „null“, prázdný text nebo „undefined“, kterou vrací funkce bez příkazu „return“ –, nedojde k přesměrování uživatele zpět.

2.5. Tlačítka „Uložit“ a „Zavřít“

• Tlačítko „Uložit“ – Uložení změn v nastavení ovládacího prvku.
• Tlačítko „Zavřít“ – Zavření dialogu s nastavením ovládacího prvku bez uložení změn.

3. Příklady

3.1. Javascriptové funkce

• attachEvent2(window, 'load', function() { var o = el('btSave'); if (o != null) o.style.display = 'none'; });
• attachEvent2(window, 'load', function() { var o = el('btDelete'); if (o != null) o.style.display = 'none'; });
• attachEvent2(window, 'load', function() { var o = el('btBack'); if (o != null) o.style.display = 'none'; });