Opakovatelnost repetition

Vlastnost zapíná či vypíná opakovatelnost segmentu ve struktuře dokumentu a nastavuje další související vlastnosti. Opakovatelnost je klíčová pro strukturu databázových tabulek dokumentu.

Tato vlastnost nastavuje shopnost opakovatelnosti segmentu v rámci dokumentu a upravuje některé rysy touto opakovatelností spojené. Vlastnost se skládá z dílčích pod-vlastností oddělených středníkem, kde dílčí nastavení type určuje vlastní opakovatelnost a další upravují potřebné chování či jiné rysy spojené s opakováním segmentů:

• type - (none|user|depend) určuje zda segment je či není v rámci rodičovské větve opakovatelní. Výchozí none indikuje běžný segment bez opakování; Zbylé volby naopak zavádějí pro segment opakovatelnost;

• area-label-by - nastavování názvu (typu) oblasti dle obsahu prvku oblasti

• filter - možnost skrýt filtrovací podmínkou některé instance opakování

• index-column - obsah indexového (prvního) sloupce v tabulkové oblasti

• init-count - výchozí počet opakování v novém dokumentu (formuláři)

• init-value - výchozí hodnota prvku opakování (při více vých. opakováních)

• irremovable - možnost zákazu odstranění již uloženého opakování ve formuláři

• gappy - ošetření děr v číselné řadě primárního klíče (true / false)

• max-count - omezení maximálního možného počtu opakování segmentu

• min-count - omezení minimálního možného počtu opakování segmentu

• noneinsertable - možnost zákazu přidání již opakování ve formuláři

• preserve-empty - ochrana nepoužitých opakování v nových dokumentech

• table-face - nastavení zobrazení opakovatelné oblasti jako tabulkového řádku

• table-face-caption - nahrazení generovaného nadpisu v hlavičce tabulkové oblasti

type - základní typ opakovatelnosti

Určuje zda segment je či není v rámci rodičovské větve opakovatelní. Výchozí none indikuje běžný segment bez opakování; Zbylé volby naopak zavádějí pro segment opakovatelnost;

Existují segmenty dokumentu, kde je nutné opakovat stejnou strukturu prvků nebo jen samotné prvky několikrát podle situace. Například odstavce v kapitole, telefony u kontaktu nebo jiné údaje. Pokud například klient může mít více adres, pak se použije vlastnost repetition na oblast adresy. Atribut repetition/type může nabývat čtyř hodnot - none, depend, user, procedure.

none - Určuje, že segment je možné zadat v daném dokumentu pouze jednou; none je výchozí hodnota vlastnosti repeat.

user - Tato hodnota stanovuje, že daný segment se bude opakovat tolikrát, kolikrát uživatel zvolí funkci "přidat" na formuláři dokumentu. Znamená to, že pokud je hodnota user zadána u segmentu, jenž má zároveň opakovaný cizí zdroj, pak závisí na uživateli, kolik opakování z cizího zdroje si vybere. U hodnoty user můžeme do kulaté závorky definovat, kolik opakování bude viditelné na formuláři při editaci dokumentu.

depend - Tuto hodnotu je možné nastavit pouze u segmentů se zdrojem typu foreign či initial (viz. dále). Při tomto nastavení opakovatelnosti se počet opakování aktuálního segmentu řídí počtem opakování segmentu zdrojového. V dokumentu se závislým opakováním se tedy nespecifikuje, které opakování zdrojového segmentu má být použito - použijí se všechna.

meta - Tato hodnota stanovuje předně to, že daný segment NENÍ součástí xml dokumentu (tj. formuláře / tisku / struktury v akci), jeho výskyt je dán procedurou nebo jiným mechanismem. Cílem tohoto nastavení je možnit SQL dotazům pro přehledy a akce dostupnost či optimálnost použití určitých dat, které v tvořené tabulce jsou nebo tato data propojue.

view - Tato hodnota stanovuje také to, že daný segment NENÍ součástí xml dokumentu (tj. formuláře / tisku / struktury v akci), není už ani ale jako tabulka v databázi. V databázi je pouze SQL nástroji zaveden stejnojmenný pohled se sterjnou strukturou polí tak, aby byl opět využitelný dotazem pro snadnější dostupnost již jinde zavedených dat.

area-label-by - nastavování názvu oblasti dle potomka

V některých aplikačních případech je zapotřebí, aby bylo pod sebe možné přidávat opakování různých druhů. Například v určitém dokumentu můžeme chtít, aby uživatel měl možnost pod sebe přidávat odstavce, obrázky a další běžné druhy. Protože celý princip XDS je koncipován tak, že je pevně dán druh opakování, je zde nabízena možnost tento pevný rámec poněkud obejít tím, že do jedné oblasti soustředíme prvky různého druhu a pak přidáme jeden prvek výběrový a do jeho seznamu uvedeme jednotlivé druhy, které může oblast reprezentovat. Na hodnotě výběru je pak možné nastavit zobrazování prvků potřebných pro určitý druh pomocí appear-if těchto prvků a ve vlastnosti area-label-by pak nastavit odkaz na tento výběrový prvek. Výběrovým prvkem je pak míněn buď prvek s roletkou select » option nebo prvek s definovaným výběrovým uzlem. Prvek bude automaticky skryt a jeho obsah bude určován při přidávání nové oblasti, kdy bude uživatel dotazován na druh, který chce přidat. Tento druh je pak v další editaci neměnný (pokud samozřejmě uživatel neprovede kroky zpět). Tímto způsobem je simulováno přidávání různých druhů opakován v rámci jednoho seznamu. Například můžeme mít oblast s názvem obsah_dokumentu a v ní různé prvky. Dále v této oblasti bude existovat prvek druh_obsahu, který bude výběrový. Pak zápis vlastnosti bude vypadat takto:

filter - filtrování instancí opakování

Zatímco vlastnost appear-if segmentu umožňuje skrýt celý segment (v případě opakovatelného segmentu jej skrývá i s ovládacími prvky a příp. hlavičkou tabulky), můžete v části filter vlastnosti repeat-behaviour definovat podmínku zobrazení pouze instancí opakování daného segmentu. Pokud tedy budeme mít položky, které nechceme z databáze úplně smazat, ale chceme jen, aby se již nezobrazovaly, můžeme na těchto položkách (v opakovatelné oblasti) definovat zaškrtávátko "Zrušeno". Pak by mohlo být využití filtru následující:

Po zaškrtnutí podmínka přestává platit a položka tedy mizí. To může být ale někdy problém. Někdy můžeme chtít zrušené položky zobrazit. Proto můžeme v rámci daného dokumentu, např. někde v hlavičce, definovat zaškrtávací volbu (prvek) "Zobrazit zrušené", jejímž zatržením se mají všechna zrušená opakování zobrazit. Pak by zápis našeho filtru vypadal následovně:

V zápisu fitru je možné odkazovat jen na místní hodnoty v rámci dokumentu a není tedy možné využívat všech možností filtrů určených pro výběr z databáze.

index-column - obsah indexového sloupce

Tato vlastnost nabízí čtyři možnosti formou následujících klíčových slov: position (výchozí), label, combine nebo none. Účelem vlastnoti je v tabulkové oblasti určit, zda se v prvním sloupci má zobrazit pořadové číslo opakování (nast. position), obecný obsah vlastnosti label (nast. label), kombinace obojího (nast. combine) nebo zda se nemá první sloupec zobrazovat vůbec (nast. none). Nejčastější a také nejpraktičtější variantou je výchozí hodnota position, která zajišťuje zobrazení zvýrazněného pořadového čísla řádku (oblasti) ve formuláři dokumentu a tiskovém náhledu.

Pokud je vlastnost index-column uvedena u netabulkového opakování oblasti či prvku, pak je možné pomocí ní vypnout tvoření indexu. Kombinování indexu se štítkem nemá dopad, neboť za indexem u netabulkové oblasti či prvku je štítek standardně řazen. Na neopakovatelné segmenty pak vlastnost nemá dopad vůbec vzhledem ke svému umístění ve složené vlastnosti repeat-behaviour.

init-count - výchozí počet opakování

Vlastnost formou celého kladného či nulového čísla nastavuje výchozí počet opakování při zadání formuláře nového dokumentu. Výchozí hodnotou této vlastnosti je jednička. Nulou docílíme nenabízení žádného opakování ve formuláři nového dokumentu a při zadání více než jednoho opakování lze s výhodou použít vlastnost init-value pro přednastavení různých hodnot v opakováních.

init-value - výchozí hodnota prvku/ů opakování

Při zadání více než jednoho výchozího opakování často bývá užitečné nastavit také různé (!) initial hodnoty prvků obsažených v opakování. Můžete tak například ve formuláři vytvořit tabulku ročního výkazu, kde jedním opakováním bude oblast míněná jako kalendářní měsíc. V takovém případě bude do výchozího počtu opakování init-count nastaven počet 12. Uvažujme dále, že v každém takovém opakování je prvek pro zadání čísla měsíce (hodnoty 1 až 12). Hodnoty měsíců pak pomocí init-value zadáme takto:

Hranaté závorky obsahují poziční číslo opakování, jehož výchozí hodnota má být přednastavována a pokud opakováním není prvek, ale oblast jako v našem příkladu, musí za hranatou zavorkou následovat jestě odkaz k prvku. Před hranatou závorkou může být ještě uváděn název opakovatelného segmentu, ale je to nepovinné a zbytečné. Při zadávání řetězcových, datumových a časoových hodnot je zapotřebí tyto hodnoty ve výrazu ohraničit apostrofy.

irremovable - možnost zákazu odstranění opakování

Opakování, která již byla uložena v databázové evidenci je možné ochránit proti odstranění nastavením vlastnosti irremovable na hodnotu true. Standardní hodnotou této vlastnosti je false. U nově přidaných opakování nebo u všech opakování v nově zadávaném dokumentu jsou tato vlastnost a její nastavení ignorována.

gappy - ošetření mezer v číslech prim. klíčů

Hodnota gappy je logická - může být tedy nastavena na true či false (resp. na yes či no). Jde o možnost vzniku tzv. děr v číselných řadách primárního klíče opakování. Parametr tyto díry povoluje - výchozí je false, tedy zákaz děr v číselné řadě. Více o těchto mezerách viz. dokumentový parametr gappy.

max-count - maximální možný počet opakování

Je-li zapotřebí omezit maximální možný počet opakování určitého opakovatlného segmentu, je nutné nastavit vlastnost max-count na hodnotu celého kladného a nenulového čísla. Plnění hodnoty nastavení je ve formuláři kontrolováno průběžně při celé editaci dokumentu. Odstraněná opakování, jež jsou ve skutečnosti jen skrytá, nejsou započítávána do kontrolovaného počtu.

POZNÁMKA: Ve formuláři se kontrola počtu opakování provádí v okamžiku přidávání či odebírání opakování. Pokud je třeba kontrolu provádět i v okamžiku ukládání dokumentu, musí být použita i kontrolní pravidla. U nových dokumentů je rovněž možné s výhodou použít vlastnost init-count.

min-count - minimální možný počet opakování

Je-li zapotřebí omezit minimální možný počet opakování určitého opakovatlného segmentu, je nutné nastavit vlastnost min-count na hodnotu celého kladného a nenulového čísla. Na rozdíl od nastavení max-count je min-count kontrolováno až při ukládání formuláře dokumentu a při zjištění překročení hranice je ukládání zastaveno. Odstraněná opakování, jež jsou ve skutečnosti jen skrytá, nejsou započítávána do kontrolovaného počtu.

POZNÁMKA: Ve formuláři se kontrola počtu opakování provádí v okamžiku přidávání či odebírání opakování. Pokud je třeba kontrolu provádět i v okamžiku ukládání dokumentu, musí být použita i kontrolní pravidla. U nových dokumentů je rovněž možné s výhodou použít vlastnost init-count.

noneinsertable - možnost zákazu přidání opakování

Skrytí tlačítka pro přidání opakování a také eliminaci všech dalších možností formuláře pro přidání instance daného opakování docílíte nastavením vlastnosti noneinsertable na hodnotu true. Opakování tak můžete svěřit např. transformační akci, která zajistí speciální okolnosti či okamžik vložení.

preserve-empty - ochrana nepoužitých opakování

Při zavádění nových dokumentů prostřednictvím webových formulářů se ověřuje, zda ve výchozím opakování (tedy ne v tom, které přidá uživatel) byla provedena najaká úprava a pokud ne, je toto opakování, ještě před odesláním na server k uložení, odstraněno. Důvodem je zbytečnost takových záznamů v drtivé většině případů. Někdy ovšem toto chování může být shledáno jako nevyhovující, a proto je k dispozici nastavení preserve-empty, které jej vypíná při zápisu:

Výchozí hodnotou při neuvedení je samozřejmě false a je možné i zde uvádět ekvivalentní hodnoty yes/no.

table-face - nastavení tabulky ve formuláři

Oblasti, které jsou opakovatelné a obsahují pouze prvky (nikoli vnořené podoblasti), mohou ve formuláři tvořit řádek tabulky s tím, že hlavička se automaticky sestaví z názvů prvků. Tohoto efektu je možné docílit nastavením vlastnosti table-face na true. Stejného efektu je docíleno, pokud výchozí koncept (vlastnost concept segmentu) u opakovatelné oblasti je nastaven na inline.

table-face-caption - nahrazení generovaného nadpisu v hlavičce tabulky

Při zadání hodnoty tato nahrazuje automaticky generovaný nadpis v hlavičce tabulkové oblasti ve formuláři dokumentu. Apostrofy nejsou nutné.

Potenciální vlastnické uzly

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

• element - prvek (segment uvnitř definice);

• area - oblast (segment uvnitř definice);

Vlastnost repetition repetition

Vlastnost zapíná či vypíná opakovatelnost segmentu ve struktuře dokumentu a nastavuje další související vlastnosti. Opakovatelnost je klíčová pro strukturu databázových tabulek dokumentu.