flexideo

Specifikace masky pro zadání údajů mask

Pro prvky umožňuje nastavit vstupní masku pro použití ve formuláři. Zamezuje zadání a / nebo upravuje zadané hodnoty tak, aby splňovali jednotnou formu.

syntax
{file-name}

Při zadávání údajů mohou nastat situace, kdy chceme provádět u některých prvků složitější kontrolu zadaných znaků či chceme usnadnit zadávání celého údaje určitými zkratkami, doplňováním zakončení načatých údajů, vkládat oddělovače apod. Za tímto účelem můžeme k prvkům připojovat tzv. masku prvku pomocí vlastnosti mask.

Jméno této masky je také obsahem této vlastnoti prvku. Výchozí hodnota vlastnosti mask je prázdný řetězec. Vlastnost mask může obsahovat pouze jediný název, který je odkazem na konkrétní masku.

Pro vytvoření chování masky je k dispozici skriptovací jazyk JavaScript v souboru masks.js na webovém sídle systému flexideo. V tomto souboru je definován objekt umsk (User Masks) pomocí konstruktoru MSKUmsk. Aby byla maska funkční, je třeba tomuto objektu pomocí jeho konstruktoru definovat metodu, jež bude mít stejný název, jaký má vlastnost mask. Tato metoda je pak volána po ukončení editace daného prvku pomocí jeho kolonky ve formuláři a to ještě před tím, než je editovaná hodnota vložena do XML dokumentu, ze kterého formulář čerpá své údaje.

Aby bylo možné sestavit smysluplnou funkcionalitu masky, je zapotřebí mít k dispozici uživatelem zadanou hodnotu, mít možnost tuto hodnotu změnit a také mít možnost stopnout ukládání uživatelem zadané hodnoty, pokud ji maska neodsouhlasí nebo není schopna opravit či doplnit. Proto jsou k dispozici následující vlastnosti objektu umsk, které jsou v metodě masky dostupné pomocí klíčového slova this:

this.isValueCorect - obsahuje hodnotu true a pokud ji tělo masky změní na false, údaj zadaný uživatelem nebude uložen;

this.inValue - obsahuje hodnotu zadanou uživatelem, která má být kontrolována či upravována maskou

this.returnValue - obsah této proměnné bude po průběhu masky uložen do dokumentu (pokud je text převoditelný na odpovídající data ukládaného prvku); výchozí hodnota je nastavena na hodnotu inValue;

this.declineReason - tato proměnná je využita v případě stopnutí ukládání hodnoty - obsahuje důvod tohoto zamítnutí uložení hodnoty, které se zobrazí uživateli;

Pro plné pochopení fungování masky je třeba vysvětlit způsoby ukládání údajů z kolonek do databáze. Uživatel zadává obsah dokumentu formou kolonek prvků rozdělených ve formuláři do oblastí. V pozadí formuláře je XML dokument odpovídající svou strukturou (stejně jako formulář) definovanému datovému dokumentu. Ve chvíli, kdy uživatel opustí upravovanou kolonku přechodem kurzoru na jiný ovládací prvek či kliknutím na jinou část dokumentu dojde k základnímu odkontrolování zadaných znaků dle datového typu prvku v pozadí a přesunu hodnoty (pokud je v pořádku a odpovídá data) tagu prvku v datovém XML dokumentu na pozadí formuláře. O tomto procesu zde hovoříme jako o uložení hodnoty kolonky do prvku. Nedochází však k vlastnímu uložení prvku do databáze. K tomu dojde až ve chvíli, kdy klikneme na nástroj pro uložení celého dokumentu do databáze nebo ve chvíli, kdy toto uložení potvrdíme na základě výzvy formuláře (např. při jeho zavírání). Maska je použita ještě před přesunem obsahu obsahu kolonky do tagu XML dokumentu a právě již zde má maska prvku možnost ukládání nesprávné hodnoty zastavit nebo ji upravit tak, aby odpovídala potřebám a také datovému typu. Po provedení zápisu pak formulář okamžitě danou hodnotu pro kontrolu opět z XML načítá do kolonky, takže případné úpravy maskou se po jejím použití okamžitě promítnou i vizuálně a uživatel tak má plnohodnotnou zpětnou vazbu.

Na příkladu jednoduché masky pro rodné ukážeme možnosti a způsoby tvorby masky. Jejím jediným úkolem nejprve bude upozornit uživatele pokud neuvede lomítko a zamezit uložení údaje.

function MSKRodneCislo(){
if ( this.inValue != "" ) //zamezíme kontrole prázdné hodnoty
if ( this.inValue.substring(6,1) != "/" ){ //je obsaženo /?
//lomitko není - zamezíme uložení
this.mskIsValueCorect = false
this.mskDeclineReason = "Rodné číslo musí obsahovat lomítko."
}
}

Nyní příklad vylepšíme tak, že na místo nepohodlného upozňování uživatele rovnou zařídíme jeho automatické přidávání pokud chybí:

if ( this.inValue != "" ) //zamezíme kontrole prázdné hodnoty
if ( this.inValue.substring(6,1) != "/" ){ //je obsaženo /?
//lomitko není - doplníme jej
this.mskReturnValue = inValue.substring(0,6) + "/" + this.inValue.substring(6,5)
}

Kontrolu bychom mohli ještě doplnit o kontrolování správnosti zadání jednotlivých částí rodného čísla, kontrola počtu zadaných znaků atd. Můžeme zařadit i kontrolu logiky, které každé ročné číslo splňuje, jako například délku části za lomítkem, podle datumu uvedeného před lomítkem. To všechno pojetí masky umožňuje. Nemusíme se příliš bát, časové náročnosti, protože kontrola kolonky pomocí masky probíhá okamžitě pouze na jednu jedinou kolonku. V momentu ukládání celého dokumentu jsou již kontroly pomocí masky provedeny. Jako poslední krok je třeba v souboru masks.js definovat v konstruktoru odkaz na připravenou masku např. takto:

this.rodneCislo = MSKRodneCislo

- obsahem vlastnosti mask u prvku s rodným číslem pak bude hodnota rodneCislo.

Vedle možností masky systém definice také nabízí možnost přímého zápisu srovnávacího vzoru pomocí vlastnosti pattern.


Potenciální vlastnické uzly

Vlastnost mask je možné uvést u následujících uzlů:

ElementDef - šablona prvku (kmenová definice) - jako parametr;

element - prvek (segment uvnitř definice);

Zákaz kopírování hodnoty prvku disclonableVlastnost place-holder place-holderVlastnost required-if required-ifPodmíněná upravitelnost prvku edit-ifVlastní šablona segmentu custom-tempFormulářový typ inputf-type kompilaceZadání počáteční hodnoty initialÚplná změna políčka vlastní šablonou field-tempVlastnost join-fromPropojená nabídka prvku linked-offerVýběr hodnoty z dodatečného seznamu lexiconSpecifikace masky pro zadání údajů maskPrvek s generováním zprávy messengerVlastnost merge mergeOtevření formuláře openedVlastnost preserveMožnost rychlé nabídky quick-offerZadání vyžadování hodnoty requiredMožnosti chování zdroje source-behaviourSpecifikace podmínky pro zdroj dat source-filterVýchozí upřesnění opakování starting-specification