Specifika formulářových akcí
1. Úvod
Formulářové akce představují zvláštní kategorii akcí systému Flexideo, která se od ostatních typů (zejména tabulkových a služebních) odlišuje svou prací s formulářovým draftem – rozpracovaným dokumentem uživatele. Tento dokument nemusí být nutně uložen v databázi a může se jednat i o nově vytvářený, dosud neuložený dokument. Existují tři základní druhy akcí:
Akce přehledu
Formulářové akce
Webové služby
Zatímco akce přehledu pracuje s daty tabulky, formulářová akce pracuje s jediným formulářovým draftem dokumentu.
2. Vstupní struktura formulářové akce
2.1. Povaha vstupu
Formulářová akce má vždy povinný vstup typu act:form-draft.Tento draft obsahuje aktuální stav formuláře, tak jak jej má uživatel právě rozpracovaný – buď nově vytvářený, nebo načtený z databáze. Na rozdíl od tabulkových akcí, které mohou mít na vstupu seznam více položek ( pdk-list), formulářová akce vždy pracuje s jedním konkrétním dokumentem jednoho typu.
2.2. Více typů draftů
Jedna akce může být vytvořena pro více typů draftů, ale v jednom okamžiku je na vstupu právě jeden.Zdrojem dat bývá otevřený pdk-list s volbou "dok", která umožňuje přístup k celému rozpracovanému draftu.
3. Průběh zpracování a návrat hodnot
3.1. Zpracování draftu
Po spuštění akce se draft přenáší z klientské části (Comex/Intranet) na server, kde může být:použit k provedení operací na straně serveru,
upraven a vrácen zpět do formuláře,
nebo zpracován bez vrácení.
3.2. Možnosti návratu
Vrácení draftu zpět – úprava se okamžitě projeví ve formuláři.
Nevrácení draftu – klientská část označí dokument jako vyřízený.
Uložení do databáze – využitím požadavku save-document.
4. Ukládání a práce s dokumentem
4.1. Save-document
Nejjednodušší způsob zpracování je použití požadavku save-document.Pokud je:
zdrojem pdk-list otevřený s volbou "dok",
typ dokumentu v obálce totožný s typem draftu,
a primární klíč odpovídá pořadníku draftu,
4.2. Kombinace více typů dokumentů
V rámci jedné akce lze v obálce save-document kombinovat více typů (např. kontakt a osoba).Každý typ odpovídá svému zdroji a ukládání probíhá samostatně. Poznámka: Na vstupu formulářové akce může být pouze jeden typ dokumentu, tedy i ukládání probíhá pouze pro tento typ.
5. Vrácení draftu do formuláře
Pokud je v obálce save-document aktivována volba „do formuláře“, nedochází k uložení do databáze, ale k vrácení úprav do klientského formuláře.Na výstupu se pak objeví uzel form-draft.
5.1. Kopírování uzlů
Každý „šedivý“ uzel (oblast, prvek) představuje kopii stejnojmenného uzlu ze vstupu na výstup.Jakmile začneme v uzlu plnit hodnoty, nastavuje se atribut changed="true", aby formulář věděl, že se hodnota změnila.
5.2. Metadata
Kromě obsahu draftu je nutné pracovat i s metadaty:primární klíče,
atributy automatizace výpočtů,
atribut deleted ( true/false),
a další atributy dle [stránky metadat dokumentů].
6. Porovnání s tabulkovými akcemi
| Typ akce | Vstup | Výstup | Charakteristika |
|---|---|---|---|
| Tabulková | pdk-list (více záznamů) | dílčí výstup / redirect | nevrací data do tabulky |
| Formulářová | form-draft (1 dokument) | draft (upravený / uložený) | vrací nebo ukládá formulářová data |
7. Práce s víceúrovňovou strukturou dokumentu
Formulářové akce často pracují s více větvenou strukturou (např. faktura › položky faktury).7.1. Relativní zdroj
Každá položka (např. polozka-faktury) se zpracovává pomocí relativního zdroje, který určuje konkrétní uzel položky.Tím lze:
přenášet položky na výstup,
filtrovat, přidávat nebo mazat položky podle podmínek.
7.2. Typické příklady
Odstranění položek › nastavení deleted="true".
Nově přidané položky › primární klíč začíná znakem #.
Přenos existujících položek › zachování klíče a případná úprava hodnot (např. cena).
8. Oblasti s cizím zdrojem
8.1. Initial a Foreign oblasti
initial – funguje obdobně jako vlastní prvky dokumentu.
foreign – zobrazuje cizí data, ale při úpravě je třeba ošetřit indikátor změny ( changed="true").
8.2. Disketka
U cizích prvků lze použít symbol disketky, který vypíná indikátor změny, aby nedošlo k nechtěnému přepisu zdrojových dat.9. Kopírování oblastí a varianty uzlů
Při přenášení oblastí mezi vstupem a výstupem se používá volba malé „c“ – kopírování bez modifikace.Pokud je potřeba provést úpravy, využívá se disketka nebo hodnotové operace. U formulářových akcí musí být vždy zachována kompletní struktura výstupu – i povinné uzly, které nejsou vyplněné, musí být ve výstupu přítomny (pomocí uzlu variant).
10. Opakovatelné segmenty a mazání
Pokud pracujeme s draftem, který již existuje v databázi:nové opakování se přidává jako nové (s klíčem #),
původní opakování zůstává, dokud není odstraněno pomocí atributu deleted="true".
11. Doporučení a upozornění
?? Upozornění:Pokud je vstupem nový dokument (s klíčem začínajícím #), není vhodné do něj vkládat klíče existujících dokumentů.
Vstupní draft je vždy jen jeden
Formulářová akce pracuje výhradně s jedním dokumentem (form-draftem) – nelze mít více typů nebo více záznamů zároveň.
Zachování struktury při vracení draftu
Při vrácení dat do formuláře musí být výstupní struktura kompletní podle definice typu – i povinné uzly, i když jsou prázdné, musí být přítomny.
Správná práce s atributem deleted a klíči
Nové položky mají klíč s „#“, mazání se provádí nastavením deleted="true". Při nesprávném použití může dojít ke ztrátě dat nebo duplicitám.
U cizích oblastí nepřepisovat zdrojová data
U prvků typu foreign je nutné ošetřit indikátor změny ( changed="true") nebo použít disketku, aby se změna nepropsala zpět do zdrojového dokumentu.
Rozlišení režimu uložení vs. vrácení do formuláře
Pokud je aktivní volba „do formuláře“, nedochází k uložení do databáze – pouze k vrácení upraveného draftu. Pro uložení je nutné explicitně použít save-document.
Příklad postupu tvorby formulářové akce: „Aktualizace položek faktury“
-
Vstup akce
- Nastav vstup typu act:form-draft pro dokument faktura.
- Zdroj nastav jako pdk-list otevřený volbou "dok" (rozpracovaný draft faktury).
- Ve zdroji vyber klíč dokumentu draftu tak, aby byla editována stejná faktura
-
Mazání neplatných položek
- V obálce akce přidej uzel pro položky s relativním zdrojem polozka-faktury.
- Použij podmínku (např. podle stavu nebo data) a položkám, které nevyhovují, nastav atribut deleted="true".
-
Přidání nových položek z databáze
- Připoj zdroj typu sql-query nebo table, který vrací potřebné nové položky.
- Přenes tyto záznamy do výstupního uzlu položek; novým položkám se automaticky vygeneruje klíč s #.
-
Zachování ostatních oblastí faktury
- Pro všechny ostatní uzly (např. hlavička, odběratel, souhrny) použij kopírovací režim „c“ – přenášej beze změny ze vstupu na výstup.
- nebo můžeš i ponechat "šedivé", protože nebudeš ukládat do databáze, ale jen přenášet na výstup;
-
Výstup akce
- Na konci akce se takto vrátí kompletní form-draft zpět do formuláře s aktualizovanými položkami.
Princip aktualizace položek faktury ve formulářové akci
-
Odebrání nevyhovujících položek
Pomocí relativního zdroje polozka-faktury se v akci vybere každá položka faktury a podmínkou (např. podle stavu, data či hodnoty) se určí, zda má být odstraněna.
Pokud položka nesplní kritérium, nastaví se jí atribut deleted="true".
Tím je označena pro odstranění při dalším uložení, avšak jen v případě, že její primární klíč nezačíná znakem # – tedy nejde o nově přidanou, dosud neuloženou položku. -
Přenesení vyhovujících položek
Položky, které kritéria splní, se přenášejí ze vstupu na výstup beze změny.
Použije se relativní zdroj stejného uzlu ( polozka-faktury) a šedivý segment obálky zajistí jejich kopírování.
Tím se zachová jejich klíč i struktura, takže systém rozpozná, že jde o existující položky určené k ponechání nebo případné editaci. -
Doplnění nových položek z databáze
Pro doplnění nových položek se použije jiný zdroj, typicky sql-query nebo table, který vrací potřebná data.
Tyto položky se vloží do uzlu položek faktury na výstupu, přičemž každá nová položka je automaticky označena primárním klíčem začínajícím #.
Formulář je následně interpretuje jako nově přidané, a při uložení ( save-document) je systém vloží jako nové záznamy v databázi.