Události formuláře

Modul Forms umožňuje reagovat na události formuláře pomocí vlastního JavaScriptu (Custom Script). Skripty se definují v souboru CustomScript formuláře a mají přístup k objektu tisa, který poskytuje Form API.

onFormInit

Spouští se před renderováním UI formuláře. V této fázi lze:

• Nastavit vlastnosti polí (readOnly, hidden, required, title).
• Zaregistrovat onChange handlery na pole.
• Přepnout definici formuláře pomocí form.setFormDefinition().
• Načítat data z externích zdrojů (funkce může být async).

Poznámka: Metoda form.setFormDefinition() může být volána pouze v onFormInit. Po dokončení této fáze je volání zakázáno.

async function onFormInit() {
  const { form } = tisa;
  const { Status, Amount } = form.field;

  // Skrytí pole na zobrazovacím formuláři
  if (form.isDisplayForm) {
    Amount.hidden = true;
  }

  // Registrace onChange handleru
  Status.onChange((value, { oldValue }) => {
    console.log(`Status změněn z ${oldValue} na ${value}`);
  });

  // Přepnutí na alternativní definici formuláře
  if (form.isNewForm) {
    form.setFormDefinition("CreateForm");
  }
}

onFormInitComplete

Spouští se po renderování UI formuláře. V této fázi je formulář plně načtený a viditelný uživateli. Vhodné pro:

• Operace, které vyžadují přístup k DOM.
• Zobrazení notifikací nebo dialogů.
• Logiku, která závisí na vykreslených hodnotách.

async function onFormInitComplete() {
  const { form } = tisa;

  if (form.isTaskForm) {
    console.log("Formulář úkolu je připraven.");
  }
}

onSubmitting

Spouští se po vestavěné validaci, ale před uložením formuláře. Funkce může:

• Provést vlastní validaci.
• Upravit hodnoty polí před uložením.
• Zrušit uložení vrácením true (nebo jakékoli truthy hodnoty).

Pokud funkce vrátí true (nebo jakoukoliv jinou nenulovou / neprázdnou hodnotu), uložení formuláře se přeruší a uživatel může opravit chyby.

async function onSubmitting() {
  const { form } = tisa;
  const { Amount, Approver } = form.field;

  // Validace: částky nad 10000 vyžadují schvalovatele
  if (Amount.value > 10000 && !Approver.value) {
    alert("Pro částky nad 10 000 je vyžadován schvalovatel.");
    return true; // Zruší uložení
  }
}

onOutcomeClicked

Spouští se, když uživatel klikne na výsledek (outcome) úkolu na formuláři úkolu. Funkce přijímá dva parametry:

• nextState — interní název cílového stavu (odpovídá stateInternalName z konfigurace workflow).
• outcome (nepovinný) — objekt vybraného přechodu s následujícími vlastnostmi:
• title — zobrazovaný název přechodu.
• titleResource — lokalizační klíč názvu.
• stateInternalName — interní název cílového stavu.
• stateId — ID cílového stavu.
• transitionInternalName — interní název přechodu.
• transitionId — ID přechodu.
• commentRequired — true, pokud přechod vyžaduje komentář.
• commentMode — režim komentáře: 0 (volitelný), 1 (povinný), 2 (skrytý).
• actionText (nepovinný) — text akčního tlačítka.

function onOutcomeClicked(nextState, outcome) {
  const { form } = tisa;

  if (nextState === "Rejected") {
    // Při zamítnutí vyžadovat komentář
    form.field.Comment.required = true;
  }

  if (outcome?.commentRequired) {
    form.field.Comment.required = true;
  }
}

Pořadí událostí

1. onFormInit — inicializace (před renderováním UI)
2. onFormInitComplete — dokončení inicializace (po renderování UI)
3. (interakce uživatele)
4. onOutcomeClicked — výběr výsledku úkolu (pouze na formuláři úkolu)
5. onSubmitting — před uložením formuláře (po vestavěné validaci)