Vytvorte si formulár ..
Zápis vzorcov v poliach iPDF formulára je pomerne intuitívny, avšak môže byť náročný na správnu syntax. Nie je možné spustiť formulár so zle zapísaným vzorcom, nakoľko všetky vzorce sa pri úvodnom načítaní formulára kompilujú do natívneho PHP kódu, ktorý sa nedokáže vykonať v prípade nesprávnej syntaxe. Na jednej strane je to obmedzenie pre dizajnéra formulára, na druhej strane záruka, že spustený formulár nemôže obsahovať syntaktické chyby. Taktiež je to jediná cesta pre dosiahnutie čo najvyššieho výpočtového výkonu a značnej flexibility poskytovanej veľkým množstvom dostupných PHP funkcií.
Funkcie pre výpočet hodnoty poľa zahŕňajú povolené natívne PHP funkcie (viac ako 250 funkcií) ako aj špeciálne iPDF funkcie určené pre prácu so samotným formulárom (cca 60 funkcií). Volať je taktiež možné aj objekty naprogramované pre individuálny formulár (non-shared resources) ako aj externé objekty (shared resources), čo poskytuje takmer neobmedzené možnosti pre interakciu formulára.
Príklady zápisu vzorcov
- formula="
number_format([HRUBY_MESACNY_PRIJEM] * [POCET_MESIACOV], 2)" - Pole bude obsahovať súčin hodnôt z polí "HRUBY_MESACNY_PRIJEM" a "POCET_MESIACOV" zaokrúhlený vždy na dve desatinné miesta.
- formula="
upper()" - Hodnota poľa obsahujúceho vzorec bude vždy zmenená na veľké písmená. Prázdny argument znamená odkaz na vlastné pole (self-reference).
- formula="
upper([PRIEZVISKO])" - Hodnota poľa bude vždy rovnaká ako hodnota poľa "PRIEZVISKO" avšak veľkými písmenami.
- formula="
if !empty([ZIADAM_VRATENIE_PREPLATKU]) then enable() else disable();reset();" - Ak je zaškrtnuté políčko "ZIADAM_VRATENIE_PREPLATKU" tak sa užívateľovi súčasné pole (nazvané napríklad "BANKOVY_UCET") sprístupní, v opačnom prípade sa zneprístupní a nastaví na úvodnú (napr. prázdnu) hodnotu.
- formula="
count(find('KATEGORIA_'))" - Zistí počet všetkých polí obsahujúcich v názve reťazec "KATEGORIA_".
- formula="
values(find('KATEGORIA_'), '>100')" - Sčíta hodnoty všetkých polí obsahujúcich v názve reťazec "KATEGORIA_", ak je ich hodnota vyššia ako 100.
Obr. 1 - Príklad zápisu vzorca
UPPER() do vstupného poľa PRIEZVISKO Odporúčané zásady pri vytváraní vzorcov
- odkaz na pole alebo konštantu musí byť uzatvorený v hranatých zátvorkách, napr. odkaz na pole PRIEZVISKO musí byť zapísaný ako
upper([PRIEZVISKO]). - Pre zápis vzorcov platie tie isté pravidlá ako pre PHP kód. Hodnoty polí teda môžete spájať, násobiť, odčítať apod. Napríklad zápis pre spojenie dvoch polí
upper([MENO].' '.[PRIEZVISKO])sa skompiluje ako$this->ipdf_upper($this->getValueIntern('MENO').' '.$this->getValueIntern('PRIEZVISKO')). - zásadne používajte jednoduché uvodzovky (single quotes) pre textové argumenty. Vzorce sa ukladajú do konfiguračného súboru typu INI pre ktorý je nutné dodržať syntaktické pravidlá. V prípade použitia je dvojité uvodzovky (double quotes) nutné escapovať opačným lomítkom.
- odporúčaný postup pri tvorbe formulára je najskôr vytvoriť dizajn a až potom definovať vzorce (najskôr vstupné, potom výstupné), pokiaľ sú potrebné.
- vzorce vkladajte po jednom najviac dvoch, priebežne resetujte dokument a preverte, či sa vzorce správne vyhodnocujú. Môžete využiť funkcie administrátorského menu "Uložiť súčasný stav", resp. "Nahrať posledný stav". Ak zadáte viac komplikovaných vzorcov súčasne môže sa stať, že ich nebudete vedieť odladiť.
- občas si urobte zálohu vstupného a výstupného deskriptora stiahnutím súboru cez file manager.
- najčastejšími chybami sú nespárované zátvorky, prípadne zabudnutá bodkočiarka. Pre zložitejšie vzorce preto radšej využite externý editor, ktorý vám ukáže správne párovanie zátvoriek.
Nasledovné bezpečnostné zásady je nutné dodržať pri vytváraní vzorcov vo formulároch:
- vzorec nesmie obsahovať žiadnu inú funkciu okrem povolených (zoznamy povolených funkcií sú uvedené nižšie)
- vzorec nesmie obsahovať žiadne priame volanie triedy, resp. objektu
- vzorec nesmie obsahovať žiadne kľúčové slová ani konštanty, napr.
__FILE__, __DIR__ apod. - vzorec nesmie obsahovať žiadne HTML tagy, napr.
<script> ..some URL/JS..</script> - vzorec nesmie obsahovať zakázané konštrukty, napr.
eval, exit, echo, include .. - vzorec nesmie obsahovať znak "dollar"
$ - vyhodnotené sú ďalšie nepovolené typy zápisov (forbidden syntax patterns)
Bezpečnosť zadávaných vzorcov
Všetky zadané vzorce sú z bezpečnostného hľadiska striktne preverené lexikálnym analyzérom. Pokiaľ vzorec obsahuje nežiadúce volanie funkcií, podozrivé časti PHP kódu, alebo nepovolené značky (tagy), bude vzorec vyhodnotený ako škodlivý a bude odstránený. Súčasne bude užívateľ varovaný o pokuse vložiť potenciálne škodlivý kód. Po druhom pokuse o zadanie škodlivého kódu bude zablokovaný aj účet užívateľa a užívateľ bude automaticky odhlásený z portálu.Zoznam podporovaných iPDF funkcií |
|||
Syntax funkcie1 |
Popis, príklad |
||
Dátové funkcie |
|||
| date ([format='d.m.Y'], [timestamp], [deltaSec]) | vráti formátovaný dátum v prednastavenom formáte d.m.Y. Formát môžete zmeniť pomocou dátumových konštánt, ktoré sú rovnaké ako pre PHP funkciu date() .
Ak chcete formátovať dátum pre konkrétny čas, môžete poslať druhý nepovinný parameter timestamp.
deltaSecs je hodnota pričítaná ku timestamp - vhodné napríklad pre formátovanie dátumu +1 hodina.
Príklad: date(), date('H:i', now() + 3600), date('H:i', now(), 3600)
|
||
| today ([format='d.m.Y']) | vráti formátovaný dnešný dátum v prednastavenom formáte d.m.Y. Alias pre zjednodušenú funkciu "date".
Príklad: today() vráti napr. 31.12.2013
|
||
| now ([format=null]) | vráti timestamp alebo formátovaný dátum, ak argument "format" nie je prázdny.
Príklad: now() vráti napr. 1277750000 alebo now('H:i') vráti 23:59
|
||
| year ([stamp=null]) | vráti aktuálny rok alebo rok pre neprázdny argument "stamp".
Príklad: year() vráti 2013 alebo year(mktime(0,0,0,12,31+1,2009)) vráti 2010.
|
||
| ddmmyyyy2ts (date) | vráti dátum prekonvertovaný na timestamp, pričom argument "date" môže mať formát DD-MM-YYYY [HH:ii:ss].
Ako delimitery možno použiť ./-.
Príklad: ddmmyyyy2ts('12.31.2010') vráti 1293750000.
|
||
Logické funkcie |
|||
| if cond then command1; [command2;..] [endif] | Vykoná príkaz "command1" a prípadne aj "command2" atď, ak je podmienka "cond" splnená. Na rozdiel od if2 nevyhodnocuje všetky argumenty. Nepodporuje vnorené if príkazy. |
||
| if2 (cond, truecommand, falsecommand) | Vykoná príkaz "truecommand", ak je podmienka "cond" splnená. V opačnom prípade vykoná príkaz falsecommand. Na rozdiel od if vyhodnocuje všetky argumenty. Podporuje neobmedzený počet vnorených if2 príkazov, tzn. nasledovný zápis je validný:
if2(cond, if2(cond, truecommand, falsecommand), falsecommand)
|
||
| if (cond1) { ... } elseif (cond2) { ... } else { ... } | Povolený natívny PHP konštrukt Podmienky "cond1, cond2, .." sú vyhodnocované po prvú, ktorá vráti TRUE. | ||
| and (cond1, cond2,..) | Vráti TRUE ak sú splnené všetky podmienky cond1, cond2, ..
if and(empty(),[SUMA]<10) then addError('Opravte sumu.')
Ekvivalentný zápis: if empty() AND [SUMA]<10 then addError('Opravte sumu.')
|
||
| or (cond1, cond2,..) | Vráti TRUE ak je splnená apoň jedna z podmienok cond1, cond2, ..
if or(empty(),[SUMA]<10) then addError('Opravte sumu.')
Ekvivalentný zápis: if empty() OR [SUMA]<10 then addError('Opravte sumu.')
|
||
Matematické funkcie |
|||
| avg (arg1, arg2, ..) | Vypočíta priemernú hodnotu z argumentov arg1, arg2, .. | ||
| sum (arg1, arg2, ..) | Vráti súčet hodnôt argumentov arg1, arg2, .. | ||
| round ([float], [precision=2]) | Vráti číslo float zaokrúhlené na precision desatinných miest. Ak je argument [float] prázdny, použije sa hodnota poľa, v ktorom sa vzorec nachádza. | ||
| roundup ([float], [precision=2]) | Vráti číslo float zaokrúhlené hore na precision desatinných miest. Ak je argument [float] prázdny, použije sa hodnota poľa, v ktorom sa vzorec nachádza. | ||
| rounddown ([float], [precision=2]) | Vráti číslo float zaokrúhlené dolu na precision desatinných miest. Ak je argument [float] prázdny, použije sa hodnota poľa, v ktorom sa vzorec nachádza. | ||
| number_format ([float, dec=2, ds=false, ts=false]) | Vráti formátované číslo zaokrúhlené na počet desatinných miest definovaný hodnotou "decimals". ds = decimal separator, ts = thousands separator. | ||
Textové funkcie |
|||
| upper([string]) | Zmení všetky písmená na veľké.
Príklad: upper("Čau") vráti ČAU
|
||
| lower([string]) | Zmení všetky písmená na malé.
Príklad: lower([MENO]), vráti "ján", ak je hodnota poľa [MENO]="Ján"
|
||
| title([string]) | Zmení všetky písmená na malé a prvé písmeno na veľké.
Príklad: title('PETER'), vráti "Peter", title('petER'), vráti tiež "Peter".
|
||
| asString([string]) | Hodnota poľa má preferenciu reťazcového typu.
Vysvetlenie: reťazec "005" je odlišne vyhodnotený pre výpočty (napríklad 005 krát 2 dá výsledok 10, úvodné nuly sú ignorované) a odlišne pre textové operácie - nuly sa vtedy neignorujú. iPDF aplikácia primárne narába s hodnotami polí ako s numerickými (číselnými) hodnotami. Ak potrebujeme vytlačiť reťazec aj s úvodnými nulami je potrebné "povedať" iPDF aplikácii, že hodnotu poľa je treba chápať ako reťazec, a nie ako číslo. Príklad: ak pole [CISLO_FAKTURY]="00123" formula=asString([CISLO_FAKTURY]) vytlačí do PDF dokumentu 00123 (správne)
formula=[CISLO_FAKTURY] vytlačí do PDF dokumentu 123 (nesprávne, nuly sa stratia)
|
||
| padLeft (string, length, char=" ") | Vyplní text "string" zľava znakom "char" tak, aby dosiahol dĺžku "length".
Príklad: ak pole [CISLO_FAKTURY]="123" padLeft([CISLO_FAKTURY], 10, "0") vytlačí do PDF dokumentu 0000000123
|
||
| padRight (string, length, char=" ") | Vyplní text "string" zprava znakom "char" tak, aby dosiahol dĺžku "length".
Príklad: ak pole [RODNE_CISLO]="801010" padRight([RODNE_CISLO], 10, "9") vytlačí do PDF dokumentu 8010109999
|
||
| concatenate (arg1, arg2,..) | Spojí argumenty arg1, arg2 atď. do jedného reťazca.
Príklad: concatenate([MENO], " ", [PRIEZVISKO]) vráti napr. Ján Novák
Rovnocenný zápis priamo v PHP by bol formula= "[MENO].' '.[PRIEZVISKO]" (všimnite si jednoduché uvodzovky v strednom argumente).
|
||
| blank ([value]) | Vráti TRUE, ak je value práve prázdny reťazec. (value === ""). | ||
| empty ([value]) | Vráti TRUE, ak je value niektorá z hodnôt 0, "", null.
|
||
| length ([value]) | Vráti celkový počet znakov v reťazci value. | ||
| left ([value=null, [length=1]]) | Vráti "length" počet znakov v reťazci "value" z ľavej strany. Ak je value null, použije sa hodnota z aktuálneho poľa. | ||
| right ([value=null, [length=1]]) | Vráti "length" počet znakov v reťazci "value" z pravej strany. Ak je value null, použije sa hodnota z aktuálneho poľa. | ||
| substring (string, start=0, length=null) | Vráti časť reťazca "string" začínajúci na znaku "start" v dĺžke "length". Ak nie je "length" uvedený, vráti všetky znaky od pozície "start" po koniec reťazca "string". | ||
| position (haystack, needle, cs=true) | Vráti pozíciu "needle" v reťazci "haystack" bez rozlíšenia (cs = false, cs = case sensitive) veľkých a malých písmen, resp. s ich rozlíšením (cs = true). | ||
| match (string, pattern) | Vráti true, ak "string" zodpovedá regulérnemu výrazu "pattern".
Príklad: formula = if !match([SUMA], '/^\d+$/') then addError('Opravte sumu.')
|
||
| number2words (number) | Vráti textovú interpretáciu čísla "number" vrátane desatinnej časti.
Príklad: number2words (15.3) vráti "pätnásť celá tri".
|
||
Funkcie pre polia |
|||
| set2 (value, [id]) | Nastaví hodnotu "value" pre pole "id".
Príklad: set2('Ján', 'MENO') nastaví do poľa [MENO] hodnotu "Ján".set2(today()) nastaví do aktuálneho poľa dnešný dátum.Pozn.: funkcia set(...) existuje tiež, avšak jej použitie nie je preferované. |
||
| reset ([id]) | Nastaví inicializačnú hodnotu poľa "id". | ||
| show ([id]) | Zobrazí pole "id".
Príklad: if [DIETA_NAD_5_ROKOV]=='ano' then show() - zobrazí aktuálne pole, ak je hodnota poľa [DIETA_NAD_5_ROKOV] nastavená na "áno".
|
||
| hide ([id]) | Skryje pole "id". Užívateľ pole nevidí.
Príklad: if ![DIETA_NAD_5_ROKOV] then hide('PRIPLATOK_ZA_NOCLAH') - skryje pole PRIPLATOK_ZA_NOCLAH, ak je hodnota poľa [DIETA_NAD_5_ROKOV] prázdna alebo nulová.
|
||
| enable ([id]) | Sprístupní pole "id" pre zápis hodnoty. Používa sa v kombinácii s disable().
Príklad: if [POISTENIE_ZAJAZDU] == 'ano' then enable('CENA_ZAJAZDU') - umožní zadanie ceny zájazdu do políčka CENA_ZAJAZDU, ak si užívateľ želá poistenie zájazdu.
|
||
| disable ([id]) | Zneprístupní pole "id" pre zápis. Užívateľ pole vidí aj s aktuálnou hodnotou, avšak nemôže do neho zapisovať. Používa sa v kombinácii s enable().
Príklad - vzorec v poli "CENA_ZAJAZDU": if [POISTENIE_ZAJAZDU] == 'nie' then reset(); disable() else enable();- zresetuje a zneprístupní pole CENA_ZAJAZDU, ak si užívateľ neželá pripoistenie. |
||
| shown ([id]) | Vráti TRUE, ak je pole "id" viditeľné pre užívateľa. | ||
| hidden ([id]) | Vráti TRUE, ak nie je pole "id" viditeľné pre užívateľa. | ||
| enabled ([id]) | Vráti TRUE, ak je pole "id" povolené pre zápis. | ||
| disabled ([id]) | Vráti TRUE, ak nie je pole "id" povolené pre zápis. | ||
| find (pattern [, cs=1[, count=0]]) | Vráti zoznam polí, ktorých názov (id) obsahuje "pattern". Ak je "count" > 0 vráti najviac "count" nájdených polí. Ak je cs=0 (case sensitive), hľadá bez ohľadu na veľké - malé písmená.
Príklad:
[VIRTUAL_POCET_VOZIDIEL]
formula="count(values(find('KATEGORIA_'), '!=\'\''))"
Do virtuálneho poľa "VIRTUAL_POCET_VOZIDIEL" sa uloží počet polí obsahujúcch v názve "KATEGORIA_", ktorých hodnota nie je prázdna.
|
||
| findmatch (pattern) | Vráti zoznam polí, ktorých názov (id) vyhovuje regulérnemu výrazu "pattern". | ||
| sort (fields [, order='']) | Usporiada zoznam polí "fields" podľa hodnôt vzostupne, resp. zostupne. Ak je hodnota order="DESC", polia sú usporiadané zostupne, inak vzostupne. | ||
| addMessage (string[, id]) | Vloží do poľa "id" informatívnu správu "string", ktorá sa zobrazí užívateľovi. Tento typ správy nemá vplyv na výkon akcií. | ||
| addError (string[, id]) | Vloží do poľa "id" chybovú správu "string", ktorá sa zobrazí užívateľovi. Tento typ správy má vplyv na výkon akcií - napríklad vytvorenie dokumentu je možné len ak sa nevyskytuje vo formulári žiadna chyba. | ||
| countMessages ([id]) | Vráti počet informatívnych správ pre pole "id". | ||
| countErrors ([id]) | Vráti počet chybových správ pre pole "id". | ||
| clearMessages ([id]) | Odstráni existujúce informatívne správy v poli "id". | ||
| clearErrors ([id]) | Odstráni existujúce chybové správy v poli "id". | ||
| caller ([property=id]) | Vráti hodnotu vlastnosti poľa, v ktorom sa práve zmenila hodnota. Hodnota "property" môže byť niektorá z hodnôt:
title, type, id, disabled, visible, event, value, valueIntern
Príklad: [VIRTUAL_UPDATE_CENA_S_DPH] formula="IF caller()=='SADZBA_DPH' THEN set2(number_format([CENA_BEZ_DPH]+[SUMA_DPH]),'CENA_S_DPH');"Ak sa zmenila hodnota poľa "SADZBA_DPH", tak aktualizujeme hodnotu v poli "CENA_S_DPH". |
||
| call (class,method [,arg1,arg2,..]) | Zavolá metódu "method" v objekte "class" s argumentami "arg1, arg2, ..".
Používa sa pri volaní objektov vytvorených pre konkrétny formulár.
Príklad:
[HLAVNA_CINNOST_POPIS]
formula="if caller()=='KOD_NACE'
then set2(call('Nace','getShortLabel',asString('KOD_NACE')));"
V políčku "HLAVNA_CINNOST_POPIS" nastaví textový popis činnosti podľa kódu NACE číselníka zisteného z poľa "KOD_NACE".
V adresári daného formulára musí existovať class "Nace" v súbori s rovnakým menom, v ktorom sa nachádza metóda "getShortLabel".
Upozornenie: Vytváranie objektov v adresári formulára nie je pre užívateľov z bezpečnostných dôvodov povolené. Kontaktujte nás v prípade, ak potrebujete súbor nahrať, s uvedením názvu konkrétneho formulára. |
||
| values (fields[, condition]) | Vráti filtrovaný zoznam hodnôt zo zoznamu "fields". Pole je vrátené, ak hodnota poľa spĺňa podmienku "condition".
Príklad:
[VIRTUAL_POCET_VOZIDIEL]
formula="count(values(find('KATEGORIA_'), '!=\'\''))"
Do poľa "VIRTUAL_POCET_VOZIDIEL" sa nastaví počet vozidiel.
Správne nastavené vozidlo má v niektorom z polí "KATEGORIA_A, KATEGORIA_B" neprázdnu hodnotu.
|
||
| templateIndex() | Vráti index kópie poľa v aktuálnej šablóne. Napr. ak je vo formulári 10 kópií šablóny "položka", tak pre všetky polia v tretej kópii vráti index "3". | ||
| templateCount([name]) | Vráti celkový počet kópií šablóny "name". Ak je "name" prázdne, zistí sa name z ID aktuálneho poľa. | ||
| formIndex() | Vráti index formulára. Napr. ak existuje 5 kópií formulára, tak pre všetky polia v druhej kópii vráti "2". | ||
| formCount() | Vráti celkový počet kópií formulára. | ||
Virtuálne polia |
|||
|
Virtuálne polia sú vstupné alebo výstupné polia, ktoré nemajú vizuálne vlastnosti.
Tzn. užívateľ ich nikdy nevidí, netlačia sa do vytvoreného dokumentu, nezobrazia sa v interaktívnom formulári ani sa neexportujú.
Odkaz na ne je však rovnaký ako pre normálne polia - tzn. ID poľa uzatvorené v hranatých zátvorkách.
Virtuálne polia slúžia najmä ako "kontajnery" pre komplexné medzivýpočty (rozklad komplexných vzorcov) alebo skryté validátory.
Virtuálne pole vždy obsahuje v názve string "VIRTUAL".
Príklad 1:
[VIRTUAL_FILL_OUT_ONE_ITEM]
formula="if empty([MAJETOK_CELKOM]) then addError('Vyplňte aspoň jednu položku.','MAJETOK_CELKOM') "
Virtuálne vstupné pole, ktoré prekontroluje, či je hodnota poľa "MAJETOK_CELKOM" prázdna.
Ak áno, nastaví upozornenie pre užívateľa.
Príklad 2: [POLOZKA_VIRTUAL_ZAKLAD_DANE_20] formula="if [POLOZKA_DPH_SADZBA]=='20' then set2([POLOZKA_JEDNOTKOVA_CENA_BEZ_DPH]*[POLOZKA_MNOZSTVO]) else set2(0)"Virtuálne vstupné pole, ktoré vypočíta základ dane pre faktúrovanú položku, ak má nastavenú sadzbu 20%. |
|||
|---|---|---|---|
1 Názvy funkcií nerozlišujú veľké a malé písmená.
2 Niektoré funkcie koexistujú paralelne ku natívnym PHP funkciám avšak sú upravené tak, aby pri nenastavenom argumente prevzali ako argument hodnotu poľa, vo vzorci ktorého sú zapísané. Napríklad funkcia empty() pracuje s hodnotou poľa, v ktorom je vzorec zapísaný, ale súčasne môže obsahovať aj odkaz na iné pole - tzn. empty([INE_POLE]).
Pozn.: Pokiaľ by ste potrebnú funkciu nenašli v zozname,
napíšte nám jej názov
spolu so stručným popisom situácie, pre ktorú potrebujete funkciu povoliť.
