Dynamické podmínky: skript

Kontext formuláře
Hlavní funkce
Čtení hodnot proměnných
Porovnávací a pomocné funkce
Validace (validateVarOn)
Vztah k builderu

Záložka Skript v okně Podmínky (viz Dynamické podmínky: builder) obsahuje celý kód dynamických podmínek úkolu v JavaScriptu. Běží v prohlížeči uživatele při vyplňování formuláře – na rozdíl od výpočtů na záložce Výpočty, které běží na serveru. Tento článek je referencí funkcí, proměnných a validací, které má skript k dispozici v TAS 5.19.12. Mechaniku přepínání mezi Builderem a Skriptem popisuje článek Dynamické podmínky: builder.

Kontext formuláře

Co	Jak ho získat
Kontext aktuálního úkolu	`const currentTask = getCurrentTask();` – obsahuje `currentTask.items` (proměnné úkolu s počátečními hodnotami z databáze), `currentTask.processVars` (proměnné případu), `currentTask.state.taskInfo` (název, vlastník, řešitel, hlavička úkolu) a `currentTask.language`.
Reference na formulářové komponenty	`const references = getReferences();`, nebo `currentTask.references`. Slouží například ke zjištění, zda uživatel proměnnou už změnil: `references['tvar_name'].isPristine()`.
Aktuální jazyk formuláře	`getLanguage()` nebo `currentTask.language`.
Data dynamické tabulky	`getDynTable(dtId, dtcId)` načte sloupec `dtcId` tabulky `dtId` (nebo jejího názvu) do `dynTable[dtId]`. Volání je asynchronní, skript počká na dokončení, než poběží dál.

Pro volání backendových služeb (Api.request.get/post/...) je k dispozici dokumentace REST API, pro obecné pomocné funkce knihovna Lodash – oboje odkazuje nápověda skriptu (tlačítko Nápověda).

Hlavní funkce

Funkce	Signatura	Popis
`hideVarOn`	`(tvar_name, condition, watchVars?, returnToPreviousState?)`	Skryje proměnnou `tvar_name`, pokud je `condition` splněná.
`varReadOn`	`(tvar_name, condition, watchVars?, returnToPreviousState?)`	Přepne proměnnou do režimu jen pro čtení.
`varMustOn`	`(tvar_name, condition, watchVars?, returnToPreviousState?)`	Udělá proměnnou povinnou.
`varWriteOn`	`(tvar_name, condition, watchVars?, returnToPreviousState?)`	Přepne proměnnou do režimu pro zápis.
`changeVarVal`	`(tvar_name, condition, value, watchVars?, force?, returnToPreviousState?)`	Nastaví proměnné novou hodnotu `value` (hodnota, nebo funkce/promise, která ji vrátí).
`varDefOn`	`(tvar_name, condition, definition, watchVars?)`	Mění definici proměnné (např. `tvar_meta`, filtr dynamického seznamu, barvu pole).
`onChangeVar`	`(tvar_name, callback)`	Zavolá `callback(tvar_name, index)` při změně proměnné.
`solveTaskOn`	`(tvar_name, condition, watchVars?)`	Pokud `condition` není splněná, znemožní splnění úkolu. Na rozdíl od `validateVarOn` se uplatní i na proměnné jen pro čtení.
`validateVarOn`	`(tvar_name, condition, validations, validationErrors, watchVars?)`	Přidá proměnné vlastní validace s hláškami. Neplatí pro proměnné jen pro čtení.
`repeatScript`	`()`	Ručně znovu spustí celý skript.

tvar_name je u všech funkcí buď název proměnné, nebo pole názvů (hromadná akce pro víc proměnných najednou). condition je buď přímo hodnota (vyhodnotí se jen při načtení formuláře), nebo funkce vracející hodnotu (přepočítá se dynamicky). watchVars omezí přepočet skriptu jen na změnu vyjmenovaných proměnných. returnToPreviousState (výchozí false) řeší, do jakého stavu se proměnná vrátí, když podmínka přestane platit: false vrací na výchozí/databázový stav, true na stav před posledním spuštěním funkce.

// Skryje pole Visa required, pokud je dopravním prostředkem služební auto
hideVarOn('Visa required', function() {
    return vSync('Means of transport') == 'Company car';
});

// Objednávka nad 200 000 Kč nejde dokončit
solveTaskOn('Estimated cost', function() {
    return vSync('Estimated cost') <= 200000;
});

// Dohledá jméno dodavatele podle ID z číselníku
changeVarVal('SupplierName', fnIsNotEmptySync(v('SupplierId')), function() {
    var supplierId = vSync('SupplierId');
    return Api.request.get('/dyn-table/12/values/' + supplierId)
        .then(function(row) { return { value: supplierId, title: row.col_1 }; })
        .catch(function() { return { title: null, value: null }; });
});

Apostrof v hlášce
Validační hlášky se ukládají do kódu v jednoduchých uvozovkách. Nepoužívejte v nich apostrof, mohl by kód podmínek poškodit.

Čtení hodnot proměnných

Funkce	Popis
`v(tvar_name)`	Hodnota proměnné úkolu. Mimo funkci/podmínku funguje jen v okamžiku načtení formuláře – pro dynamické přepočty použijte `vSync`.
`vSync(tvar_name)`	Totéž, ale platí i uvnitř funkcí, které se přepočítávají dynamicky.
`vObj(tvar_name)` / `vSyncObj(tvar_name)`	U proměnných typu výběr vrátí objekt `{title, value}` místo samotné hodnoty.
`procV(tvar_name)` / `procVSync(tvar_name)`	Hodnota proměnné případu (nikoli aktuálního úkolu).
`procVObj(tvar_name)` / `procVObjSync(tvar_name)`	Totéž jako `vObj`, ale pro proměnnou případu.

Porovnávací a pomocné funkce

Funkce	Popis
`fnEq(value1, value2)` / `fnEqSync(...)`	`value1 === value2`.
`fnNe(value1, value2)` / `fnNeSync(...)`	`value1 !== value2`.
`fnEqArray(value, array)` / `fnNeArray(value, array)` (+ `Sync`)	`true`, pokud se `value` rovná (nerovná) alespoň jedné hodnotě pole.
`fnGt`, `fnGe`, `fnLt`, `fnLe` (+ `Sync`)	Porovnání `>`, `>=`, `<`, `<=`. Argumenty mohou být i funkce.
`fnLike(value1, value2)` / `fnNLike(...)` (+ `Sync`)	`value1` obsahuje/neobsahuje `value2`.
`fnIsEmpty(value)` / `fnIsNotEmpty(value)` (+ `Sync`)	Hodnota je/není `undefined`, `null`, `''`, `[]` nebo `{}`.
`fnAnd(...)` / `fnOr(...)` (+ `Sync`)	Logické AND/OR libovolného počtu hodnot nebo funkcí.
`jsonSumArray(json, pathInJson)` (+ `Sync`)	Součet čísel v poli uvnitř JSON podle cesty, např. `obj.arr`.
`formatEmails(emails)` (+ `Sync`)	Naformátuje pole e-mailů na text oddělený středníkem – typicky v kombinaci s `changeVarVal(..., force=true)`.
`canSolveTask(bool)`	Při `false` zešedne tlačítka pro splnění úkolu (podobně jako `solveTaskOn`, ale bez vazby na konkrétní proměnnou).

Validace (`validateVarOn`)

Validace	Hodnota	Kontroluje
`isExisty`	`true`	Není `null` ani `undefined`.
`isEmptyString`	`true`	Prázdný řetězec.
`isEmail` / `isEmails`	`true`	E-mail, resp. e-maily oddělené středníkem.
`isUrl`	`true`	Platná URL adresa.
`isTrue` / `isFalse`	`true`	`value === true` / `value === false`.
`isNumeric` / `isInt` / `isFloat`	`true`	Číslo, celé číslo, desetinné číslo.
`isAlpha` / `isAlphanumeric` / `isWords` / `isSpecialWords`	`true`	Jen písmena / písmena a číslice / s mezerami / včetně diakritiky.
`isLength`	číslo	Přesná délka textu.
`minLength` / `maxLength`	číslo	Minimální/maximální délka.
`minValue` / `maxValue`	číslo	Minimální/maximální hodnota.
`isLowerThan` / `isHigherThan` / `isLowerOrEqualThan` / `isHigherOrEqualThan`	číslo, datum	Porovnání s hodnotou nebo datem.
`isDate`	hodnota	Platné datum podle lokalizace.
`isIC`	`true`	Identifikační číslo (IČO).
`isTelephoneNumber`	`true`	Telefonní číslo.
`isPath`	`true`	Cesta k souboru.
`matchRegexp`	regulární výraz	Test proti libovolnému regexu.
`equals` / `equalsField`	hodnota / název proměnné	Rovnost s konstantou, resp. s jinou proměnnou.
`isValid`	`boolean`	Libovolná vlastní podmínka – při `false` se zobrazí hláška.

validateVarOn('ReturnDate', true, function() {
    return { isHigherThan: vSync('DepartureDate') };
}, { isHigherThan: { cs: 'Datum návratu musí být po datu odjezdu.', en: 'Return date must be after the departure date.' } });

Vztah k builderu

Builder a skript ukládají jeden společný kód. Blok builderu se zapíše jako volání funkce s komentářem /** @BuilderBlock */ nad ním; vypnutý blok se navíc označí @BuilderInactive a zůstane v kódu jako komentář. Při přepnutí na záložku Builder aplikace tato označená volání přemění zpět na bloky – kód mezi nimi, kterému builder nerozumí, zobrazí jako blok typu Skript. Pokud do označeného volání zapíšete něco, co už builder nedokáže převést zpět, zůstanete na záložce Skript s hláškou Konverze skriptu do builderu se nezdařila. Podrobnosti a příklad v článku Dynamické podmínky: builder.

Související: Dynamické podmínky: builder, Dynamické řádky: skript, Výpočty na úkolu.

Dynamické řádky: skript

(opens in a new tab)