/
Layout Guide

Layout Guide

Owned by Jakub Kovář
Last updated: 11.10.2021

Migrated to MD

 

Táto stránka obsahuje dokumentáciu ku layoutom pre verziu NAE 4.2.0

Existujú 3 layoutovacie algoritmy. Každý transition môže využívať iný algoritmus. Pokiaľ nemá transition uvedený žiaden algoritmus, bude použitý legacy algoritmus (odpovedajúci správaniu na verziách NAE < 4.0.0).

Form builder aktuálnej verzie modelera (0.4.0) negeneruje XML s novým layoutom.

XSD Schéma

Transition

<xs:element name="layout"> <xs:complexType> <xs:sequence> <xs:element ref="cols" minOccurs="0"/> <xs:element ref="rows" minOccurs="0"/> <xs:element ref="offset" minOccurs="0"/> <xs:element name="fieldAlignment" type="fieldAlignment" minOccurs="0"/> <xs:element ref="hideEmptyRows" minOccurs="0"/> <xs:element ref="compactDirection" minOccurs="0"/> </xs:sequence> <xs:attribute name="type" type="layoutType"/> </xs:complexType> </xs:element>

cols - určuje počet stĺpcov layoutu celého transition-u, pokiaľ nie je uvedená žiadna hodnota je počet stĺpcov nastavený na 4.

rows - momentálne sa nevyužíva.

offset - konfiguruje globálny offset data fieldov v ich bunkách od kraja. (nezmenená funkcionalita voči verzii 4.1.0)

fieldAlignment - konfiguruje globálne nastavenie toho kam v rámci svojich buniek majú byť zarovnané data fieldy. Povolené hodnoty sú top, center a bottom

hideEmptyRows (od verzie 5.7.0) - konfiguruje pravidlo pre skrývanie riadkov. Povolené hodnoty sú all, compacted a none. Ovplyvňuje správanie grid layoutu.

compactDirection (od verzie 5.7.0) - konfiguruje pravidlo pre presúvanie referencovaných fieldov na voľné miesta. Povolené hodnoty sú none a up. Ovplyvňuje správanie grid layoutu.

atribút type - určuje aký layoutovací algoritmus má byť v tasku defaultne využívaný. Pokiaľ nie je uvedená žiadna hodnota, je použitý legacy layout. Povolené hodnoty sú legacy, flow a grid

Príklad

<transition> <layout type="legacy"> <cols>4</cols> <fieldAlignment>center</fieldAlignment> </layout> </transition>

Data Group

<xs:element name="dataGroup"> <xs:complexType> <xs:sequence> <xs:element ref="id"/> <xs:element ref="cols" minOccurs="0"/> <xs:element ref="rows" minOccurs="0"/> <xs:element name="layout" type="layoutType"/> <xs:element ref="title" minOccurs="0"/> <xs:element ref="alignment" minOccurs="0"/> <xs:element ref="stretch" minOccurs="0"/> <xs:element ref="hideEmptyRows" minOccurs="0"/> <xs:element ref="compactDirection" minOccurs="0"/> <xs:element ref="dataRef" maxOccurs="unbounded" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element>

cols - počet stĺpcov layoutu danej data groupy. Nemôže byť väčší ako počet stĺpcov nastavený v transition-e. Pokiaľ je menší využíva sa iba prvých N stĺpcov z ľava.

rows - momentálne sa nevyužíva.

layout - určuje layoutovací algoritmus pre danú data group-u. Pokiaľ nie je uvedená žiadna hodnota, preberá sa hodnota z transition-u. V prípade, že sa data grupa presunula do iného transition-u cez task ref, dedí svoje správanie z toho transition-u do ktorého bola presunutá. Povolené hodnoty sú legacy, flow a grid

alignment - určuje kam sa majú zarovnať fieldy pokiaľ nevedia vyplniť celý riadok data groupy. Pokiaľ nie je uvedená žiadna hodnota, je použitá hodnota start. Povolené hodnoty sú start, center a end. Ovplyvňuje správanie lagacy a flow layoutov.

stretch - určuje, či majú byť fieldy roztiahnuté na celú šírku data groupy. Pokiaľ nie je uvedená žiadna hodnota, je použitá hodnota false. Ovplyvňuje správanie lagacy a flow lay.outov.

hideEmptyRows (od verzie 5.7.0) - konfiguruje pravidlo pre skrývanie riadkov. Povolené hodnoty sú all, compacted a none. Ovplyvňuje správanie grid layoutu.

compactDirection (od verzie 5.7.0) - konfiguruje pravidlo pre presúvanie referencovaných fieldov na voľné miesta. Povolené hodnoty sú none a up. Ovplyvňuje správanie grid layoutu.

Príklad

<dataGroup> <cols>3</cols> <layout>flow</layout> <alignment>start</alignment> <stretch>true</stretch> <dataGroup>

Data Ref

<xs:element name="dataRef"> <xs:complexType> <xs:sequence> <xs:element ref="id"/> <xs:element ref="logic"/> <xs:element ref="layout" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="layout"> <xs:complexType> <xs:sequence> <xs:element ref="x"/> <xs:element ref="y"/> <xs:element ref="rows"/> <xs:element ref="cols"/> <xs:element ref="offset"/> <xs:element ref="template" minOccurs="0"/> <xs:element ref="appearance" minOccurs="0"/> <xs:element name="alignment" type="fieldAlignment" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element>

x - súradnica stĺpca v ktorom sa nachádza ľavý horný roh data fieldu. Stĺpec úplne vľavo má hodnotu 0. Ovplyvňuje správanie grid layoutu.

y - súradnica riadku v ktorom sa nachádza ľavý horný roh data fieldu. Najvyšší riadok má hodnotu 0. Ovplyvňuje správanie grid layoutu.

rows - určuje koľko riadkov zaberá data field (aká je jeho výška). Ovplyvňuje správanie grid layoutu.

cols - určuje koľko stĺpcov zaberá data field (aká je jeho šírka). Ovplyvňuje správanie grid layoutu.

offset - konfiguruje offset data fieldu v jeho bunkách od kraja. Sčítava sa s nastavením na úrovni transition-u (nezmenená funkcionalita voči verzii 4.1.0)

template - určuje akým spôsobom sa má data field zobrazovať vo svojich bunkách. Pokiaľ nie je uvedená žiadna hodnota, je použitá hodnota material. Povolené hodnoty sú netgrif a material. Pokiaľ je hodnota netgrif, tak sa názov data fieldu nachádza v ľavej polovicy vyhradeného miesta a samotný input v pravej polovici (správanie ako vo verziách < 4.0.0). Pokiaľ je hodnota material je input roztiahnutý na celé miesto vyhradené pre data field a názov sa zobrazuje nad input-om. (nezmenená funkcionalita voči verzii 4.0.0)

appearance - určuje výzor input elementov data fieldov podľa Material Design-u. Ovplyvňuje iba tie data fieldy, ktoré obsahujú input elementy (napr. boolean field nie je ovplyvnený). Pokiaľ nie je uvedená žiadna hodnota, je použítá hodnota outline. Povolené hodnoty sú standard, outline, fill a legacy. (nezmenená funkcionalita voči verzii 4.0.0)

alignment - umožňuje prepísať globálne nastavenie fieldAlignment z transition-u. Povolené hodnoty sú top, center a bottom

Príklad

<dataRef> <layout> <x>2</x> <y>2</y> <rows>1</rows> <cols>2</cols> <template>material</template> <appearance>outline</appearance> </layout> </dataRef>

Správanie

Táto sekcia obsahuje všeobecné správanie a pravidlá, ktorými sa riadi layoutovací algoritmus. Príklady a ukážky jednotlivých layout-ov sa nachádzajú v ďalších sekciách.

Všetky layout-y pracujú v mriežke a algoritmus ovplyvňuje iba to, akým spôsobom sa data fieldy ukladajú do jednotlivých buniek. Riadky mriežky prispôsobujú svoju výšku najvyššiemu prvku v nich. Pokiaľ sa na výšku rozťahuje prvok, ktorý zaberá viac riadkov, tak sa riadky rozťahujú rovnomerne. Layoutovací algoritmus neumožňuje vytvárať layout s prázdnymi raidkami.

Každá data group-a je nezávislý prvok v layoutovacom algoritme. Ich layout sa vyhodnocuje samostatne a skladajú sa jedna za druhú do výslednej mriežky. To znamená, že pokiaľ nemá data ref svoju data grupu správa sa ako keby bol v samostatnej data groupe (keďže sa takým spôsobom posiela na frontend). Data grupy samostatných data refov sa správajú ako keby mali legacy layout a stretch nastavený na true. Tým pádom sa rozťahujú na celú šírku tasku (správanie ako vo verziách < 4.0.0).

Data group-a ktorá má viditeľný apoň jeden data field a má názov zobrazuje tento názov. Názov je prvkom mriežky a tak v nej fyzicky zaberá miesto jedného riadku.

Mriežka neumožňuje zobrazovať elementy, ktoré by sa prekrývali. Pokiaľ takáto situácia nastane (grid layout), je do konzoly vyhodená chyba v ktorej sa uvádza identifikátor oboch prvkov, ktoré sa prekrývajú, spolu so súradnicami bodu mriežky v ktorom ku prektyvu dochádza. Identifikátory vo formáte group<číslo> prislúchajú názvom data grúp. Identifikátory používané mriežkou vychádzajú z identifikátorov data fieldov v siety, ale nekopírujú ich úplne. Neobsahujú špeciálne znaky a môžu obsahovať variácie, ktoré zabezpečia ich unikátnosť aj po spomýnaných úpravách.

Legacy layout

Legacy layout kopíruje správanie layoutovacieho algoritmu z verzií < 4.0.0.

Legacy layout vyžaduje, aby mala data grupa nastavené presne 4 stĺpce, v opačnom prípade si túto hodnotu zmení a zobrazí warning.

Fieldy sa ukladajú cik-cak z lava doprava do dvoch stĺpcov. Posledný field je umiestnený v lavo, v stede, alebo v pravo podla nastavenia v alignment atribúte data grupy.

Pokiaľ sú nejaké fieldy skryté, tak sa ostatné fieldy vyposúvajú cik-cak aby zabrali ich miesta (správanie ako vo verziách < 4.0.0).

Príklad

Flow Layout

Flow layout je podobný ako legacy layout, ale funguje s ľubovolným počtom stĺpcov. Každý data field zaberá jednu bunku mriežky a sú umiestňované cik-cak, rovnako ako pri legacy layoute.

Pre skryté fieldy je správanie taktiež rovnaké, ako pre legacy layout. Taktiež je možné použiť stretch atribút, v tom prípade je správanie úplne rovnaké, ako pri legacy layoute.

Príklad

Grid Layout

Layout je určený x a y súradnicami a rows a cols atribútmi jednotlivých data ref-ov.

Treba dať pozor na to, že súradnice udávajú globálnu polohu v celom tasku a tým, že názvy data grúp sú v layoute fyzisky prítomné a teda zaberajú riadky. Teda napríklad data grupa, ktorá je prvá a má názov má už riadok s indexom 0 obsadený.

Posúvanie data fieldov v rámci data grupy je konfigurovateľné (od verzie 5.7.0) pomocou atribútov hideEmptyRows a compactDirection. Pokiaľ data grupa nedefinuje tieto atribúty zdedia sa z konfigurácie uvedenej v nadradenom transition. Pokiaľ transition nedefinuje tieto atribúty použijú sa default hodnoty.

Default hodnoty pre verziu 5.7.0 sú:

hideEmptyRows: all

compactDirection: none

Vo verziách <5.7.0 toto správanie nie je možné konfigurovať. Layout sa správa akoby boli tieto atribúty nastavené nasledovne:

hideEmptyRows: all

compactDirection: up

compactDirection

Určuje akým spôsobom sa majú fieldy “skompaktňovať“.

none - fieldy sa neposúvajú zo svojich pozícií

up - pokiaľ je nad fieldom voľné miesto do ktorého sa field zmestí posunie sa nahor. Fieldy sa posúvajú nezávisle na sebe, takže fieldy definované v rovnakom riadku môžu skončiť v rôznych riadkoch vo výslednom layoute.

hideEmptyRows

Určuje čo sa má stať s riadkami, ktoré nepobsahujú žiadne fieldy.

all - všetky riadky ktoré sú vo výslednom layoute prázdne sú z layoutu odstránené

compacted - riadky, ktoré sa vyprázdnia tým, že sa z nich presunú fieldy pri skompaktňovaní sú odstránené. Riadky ktoré neobsahujú žiadne viditeľné fieldy sú zachované.

none - všetky prázdne riadky zostávajú vo výslednom layoute

Príklady

Task ref

Task ref is a special data variable type introduced in NAE 4.1.0 . It allows referencing other tasks and to display their content within tasks.

Task ref mechanics

A task ref field is never displayed in the layout, only its content is displayed. The server resolves the content of the referenced tasks and places the resulting data groups AFTER the current data group. The position of the task ref within the current data group does not affect where the referenced data groups end up.

Behavior for NAE < 5.7.0 and NAE 6.0.x

That is the content is displayed immediately following the current data group, any fields that are in the same data group as the task ref are displayed before the referenced content, regardless of their relative position to the task ref in their data group.

Since the data groups are rendered IN ORDER and the task ref field places the data groups it contains AFTER its host data group the content is displayed immediately following the host data group.

If a task that contains less columns than the host task is referenced only the leftmost N columns will be used to display its content. Where N is its width.

If a task that contains more columns than the host task is referenced a layouting error will be thrown and the layout won’t display at all.

Example

Layout in builder
Layout in application

Behavior for NAE 5.7.x and >= 6.1.0

The content of task refs is displayed in-place. That is wherever the task ref is in the host data group its content will be inserted at its position, pushing any other content down.

Each data group is now contained in a separate grid for rendering and can therefore have a different number of columns in its layout. All data group are stretched horizontally to fit the same space - a data group with more columns has a larger number of narrower columns, but the total width is the same.

Example

Layout in builder
Layout in application