Náhled položky (table.item.preview)

Modifikátor comex.table.item.preview zobrazuje detail jedné položky existujícího přehledu. Typické použití je ve složce záznamu: uživatel otevře položku z tabulky, stránka dostane její key a type a náhled zobrazí údaje vybraného záznamu, například obchodní příležitosti nebo zakázky.

Náhled přebírá sloupce, jejich štítky, formátování a řádkové nástroje z definice podkladového přehledu. Hodnoty zobrazuje jako dvojice štítek a obsah, při dostatečné šířce vedle sebe. Bez nastavení sekcí tvoří údaje jeden společný blok.

Vložení do stránky a výběr položky

V editoru stránek zvolte Přehled » Položka » Náhled a vyberte podkladový přehled. V XML má zdroj komponenty podobu comex.table.item:ID_PŘEHLEDU.preview:

<cxd:component xmlns:cxd="http://www.flexideo.com/comex/definition"
               source="comex.table.item:6789.preview">
  <cxd:with-param name="columnWidth" data-type="number" content="200"/>
  <cxd:with-param name="hideEmptyCells" data-type="string" content="de"/>
  <cxd:with-param name="defaultToolAtTop" data-type="boolean" content="true"/>
</cxd:component>

ID 6789 i názvy sloupců v dalších příkladech jsou ilustrativní; nahraďte je údaji své aplikace. Prefix cxd označuje namespace http://www.flexideo.com/comex/definition. Ukázky samotných parametrů patří dovnitř cxd:component.

V běžném režimu náhled používá klíč key a typ type z URL. Podle typu vybere příslušný tabulkový dotaz a omezí jej na klíč položky, standardně pdk. Kontext lze nahradit společným parametrem substitution. Sekce a ostatní vzhledové parametry tento výběr dat nemění.

Parametr ignoreKey=true vazbu na konkrétní klíč vypne. Dotaz se pak řídí zbývajícími podmínkami přehledu; náhled zobrazí první vrácený datový řádek. Pro běžný detail vybrané položky proto ponechte ignoreKey vynechaný nebo nastavte false.

Zobrazení sloupců a hlavičky

Viditelnost sloupců se řídí jejich nastavením pro položkový výstup v podkladové definici (item-output). Sloupec skrytý v běžné tabulce tak může být v náhledu viditelný. Samotné uvedení v sections však skrytý sloupec nezpřístupní.

Pokud definice přehledu určuje sloupec nadpisu pomocí grid-features/@caption-col, jeho hodnota se zobrazí v hlavičce komponenty a neopakuje se mezi údaji. showCaptionLabel určuje, zda bude před hodnotou také štítek tohoto sloupce. Bez sloupce nadpisu se hlavička odvozuje od názvu přehledu a označení vybrané položky; lze použít vlastní nadpis a popis komponenty.

Náhled zachovává formátovací šablony, HTML obsah hodnot, zvýraznění i vložené COMEX controly. Hodnotu složenou z více přímých elementů DIV umí zobrazit jako podtabulku; její ohraničení řídí showSubtableBorders. Obsah určený pro druhý řádek (second-line) zůstává pod údaji ve výchozím bloku, při použití sekcí ve výchozí sekci.

Registrované parametry

Sloupec Při vynechání popisuje chování aktuální implementace, pokud parametr v XML vůbec není.

Parametr	Typ a hodnoty	Při vynechání	Význam
columnWidth	Celé číslo, pixely.	Šířka podle běžných stylů.	Šířka jedné dvojice štítek–hodnota. Podle dostupného místa se více údajů skládá vedle sebe.
showSubtableBorders	Boolean.	false.	Zobrazí oddělovací čáry mezi řádky podtabulky vzniklé z více elementů DIV v jedné hodnotě.
ignoreKey	Boolean.	false.	Vypne omezení dotazu na klíč položky. Typické použití je samostatně filtrovaný či souhrnný údaj.
defaultToolAtTop	Boolean.	false.	Přesune výchozí řádkový nástroj do hlavičky.
otherToolsAtTop	Registrace nabízí 1 až 9 a all.	0, žádné další nástroje nahoře.	Počet dalších řádkových nástrojů umístěných v hlavičce. Omezení volby all je uvedeno níže.
hideEmptyCells	Řetězec e, de, ce, cde.	Buňky se tímto parametrem neskrývají.	Skryje prázdné hodnoty, případně také pomlčku nebo bílý čtverec; viz následující tabulka.
showCaptionLabel	Boolean.	false.	Přidá štítek před hodnotu sloupce použitého v hlavičce. Ostatní hlavičky neovlivňuje.
sections	Pole objektů sekcí.	Jeden společný blok.	Rozdělí údaje podle pravidel v kapitole Sekce náhledu.
noLabel	Čárkový seznam odkazů na sloupce.	Štítky viditelné.	Skryje štítky vyjmenovaných údajů, zachová jejich hodnoty a formátování.
textInfo	Řetězec.	Bez textové informace.	Prostý text pod daty a všemi nástroji.
htmlInfo	Řetězec s HTML.	Bez HTML informace.	Formátovaný obsah pod daty a všemi nástroji.

Editor u showSubtableBorders, ignoreKey, defaultToolAtTop a showCaptionLabel předvyplňuje při přidání hodnotu true; u hideEmptyCells nabízí jako počáteční e. Tato předvolba editoru se liší od úplného vynechání parametru. Požadované chování proto nastavte výslovně.

Skrývání prázdných buněk

Hodnota hideEmptyCells	Co se skryje
e	Prázdný obsah.
de	Prázdný obsah nebo samotná pomlčka -.
ce	Prázdný obsah nebo samotný bílý čtverec ⬜.
cde	Prázdný obsah, pomlčka - nebo bílý čtverec ⬜.

Prázdnou načtenou hodnotu náhled běžně nahrazuje pomlčkou. Chcete-li skrýt také takto zastoupené prázdné údaje, použijte de nebo cde. Parametr vyhodnocuje obsah buňky; nejde o obecný test toho, zda libovolné HTML působí vizuálně prázdně.

Nástroje a společná nastavení

Náhled používá řádkové nástroje podkladového přehledu, například otevření složky, editaci, dokumentový náhled nebo akci. Respektuje jejich podmínky a dostupnost. Nástroje, které nejsou přesunuty do hlavičky, zůstávají pod údaji. Sekce nemají vlastní oddělené nástrojové lišty.

Přesun nástrojů nahoru se neuplatní při současném skrytí nadpisu i popisu, při vizuálním sloučení komponenty nebo v integraci. Volba all je sice registrovaná, aktuální implementace však hodnotu otherToolsAtTop před jejím zpracováním převádí na číslo. Pro přesun nástrojů proto použijte číselný počet; na all se v této verzi nespoléhejte.

Z rozsahu table.item je zděděn parametr allowDataCopying (boolean). Povoluje nebo zakazuje kopírování dat přes kontextovou nabídku; při vynechání platí aplikační nastavení. Dále lze použít společné parametry tabulkových komponent, například jazykové objekty customHeader a customDescription, hiddenHeader, hiddenDescription, compactHeader, substitution či visualMerge. Jejich obecný význam se nemění; datový nadpis z caption-col má vlastní pravidla popsaná výše.

Sekce náhledu

Sekce umožňují rozdělit údaje jedné položky do tematických celků, například základních údajů, termínů a fakturačních informací. Každá sekce může mít vlastní název, ikonu a oddělovací čáru. Nastavení mění uspořádání již načtených údajů, nikoli tabulkový dotaz nebo formát hodnot.

Zadání v editoru a struktura parametru

Přidejte parametr Sekce náhledu (sections) jako pole a jednotlivé sekce do něj jako objekty. V každém objektu nastavte vlastnost Sloupce (columns). Její doprovodný výběrový nástroj nabídne sloupce podkladového přehledu a umožní vybrat více hodnot.

columns je jeden řetězec s odkazy oddělenými čárkou, například $E10101976,$E10101977. Nejde o vnořené pole jednotlivých sloupců. Odkazy určují identitu sloupců; do seznamu se nevkládají jejich aktuální datové hodnoty. Mezery kolem odkazů a velikost písmen nemění identifikaci.

Vlastnost objektu sekce	Typ	Výchozí chování
columns	Povinný řetězec, čárkový seznam odkazů $E….	Pořadí odkazů určuje pořadí údajů uvnitř sekce.
index	Nezáporné celé číslo od 0.	Bez indexu následuje sekce za výchozí sekcí podle pořadí definice, s ohledem na rezervované pozice.
title	Jazykový objekt s aliasy cs, sk, en apod.	Bez názvu. Použije se překlad pro jazyk stránky; pokud chybí, název se nezobrazí a jiný jazyk jej nenahradí.
icon	Název existujícího SVG/PNG souboru nebo absolutní cesta od /.	Bez ikony. Používá běžné vyhledání ikon COMEXu.
iconSize	Celé číslo 16, 24, 32 nebo 64, pixely.	24; stejná velikost se použije při nepodporované hodnotě.
separator	Boolean.	true, tenká čára před sekcí. První skutečně zobrazená sekce čáru nemá.

Název sekce je prostý text. Ikona může být uvedena i bez názvu. Relativní název SVG se hledá v /unk/comex/images/ico/svg/, název PNG v nakonfigurované ikonové sadě. Soubor musí v dané aplikaci existovat.

Výchozí sekce a rozdělení sloupců

Výchozí sekce vzniká automaticky a do pole sections se nezapisuje. Obsahuje všechny zbývající viditelné sloupce, které nepřevzala žádná z definovaných sekcí, v původním pořadí přehledu. Zůstává v ní také případný druhý řádek.

• Sloupec patří první sekci, která jej uvede v pořadí objektů v definici. Pozdější výskyty, i uvnitř stejného objektu, se ignorují bez chyby.
• Vizuální řazení pomocí index toto přiřazení nemění. Sekce posunutá před jinou sekci tím nezíská její sloupce.
• Sloupec použitý v hlavičce zůstává v hlavičce. Skryté sloupce se samotným vyjmenováním nezobrazí.
• Neznámý odkaz se přeskočí s diagnostickou zprávou v žurnálu COMEXu; ostatní údaje zůstanou dostupné.
• Sekce bez viditelných údajů se celá vynechá, včetně názvu, ikony a čáry. Platí to také po hideEmptyCells a pro prázdnou výchozí sekci.

Hodnoty se do sekcí přesouvají. Opakovaný odkaz proto nevytváří druhý výskyt stejného HTML obsahu nebo interaktivního controlu. Bez sections nebo při prázdném poli zůstává původní uspořádání v jednom bloku.

Pořadí sekcí a kolize indexů

Jedinečné explicitní indexy nejprve rezervují pozice. Výchozí sekce obsadí první volnou pozici od 0. Potom zbývající volné pozice obsadí sekce bez indexu v pořadí definice.

Pokud více sekcí používá stejný index, ignoruje se tento index u všech z nich. Dotčené sekce se řadí jako sekce bez indexu; kolize není chyba. Neobsazené indexy nezanechávají na stránce prázdné místo a sekce bez viditelných údajů se při vykreslení vynechají.

Následující příklady předpokládají, že všechny uvedené sekce i výchozí sekce mají viditelné údaje:

Definice sekcí v uvedeném pořadí	Výsledné pořadí
A bez indexu, B bez indexu.	Výchozí, A, B.
A s index=0, B bez indexu.	A, výchozí, B.
A s index=2, B bez indexu.	Výchozí, B, A.
A s index=0, B s index=0.	Výchozí, A, B.

Oddělovací čára patří k následující sekci: separator=false ji vypne před touto sekcí. Před první viditelnou sekcí se čára nevykreslí ani při separator=true.

Příklad dvou sekcí

První objekt vyčlení dva údaje do sekce Základní údaje a přesune ji na začátek. Další nevyjmenované údaje budou ve výchozí sekci. Sekce Termíny bude následovat za ní, bez oddělovací čáry. Pokud žádné zbývající údaje ani druhý řádek nejsou, výchozí sekce se vynechá.

<cxd:with-param name="sections" operator="array">
  <cxd:value operator="object">
    <cxd:value alias="columns" data-type="string" content="$E10101976,$E10101977"/>
    <cxd:value alias="index" data-type="number" content="0"/>
    <cxd:value alias="title" operator="object">
      <cxd:value alias="cs" data-type="string" content="Základní údaje"/>
      <cxd:value alias="sk" data-type="string" content="Základné údaje"/>
      <cxd:value alias="en" data-type="string" content="Basic details"/>
    </cxd:value>
    <cxd:value alias="icon" data-type="string" content="table-preview.svg"/>
    <cxd:value alias="iconSize" data-type="number" content="24"/>
  </cxd:value>
  <cxd:value operator="object">
    <cxd:value alias="columns" data-type="string" content="$E10101978,$E10101979"/>
    <cxd:value alias="title" operator="object">
      <cxd:value alias="cs" data-type="string" content="Termíny"/>
      <cxd:value alias="sk" data-type="string" content="Termíny"/>
      <cxd:value alias="en" data-type="string" content="Dates"/>
    </cxd:value>
    <cxd:value alias="separator" data-type="boolean" content="false"/>
  </cxd:value>
</cxd:with-param>

Skrytí štítků vybraných údajů

Parametr Sloupce bez štítku (noLabel) obsahuje čárkový seznam odkazů na sloupce. Stejně jako u sections[].columns lze použít doprovodný výběr sloupců v editoru.

<cxd:with-param name="noLabel" data-type="string"
                content="$E10101976,$E10101977"/>

Skryje se pouze štítek údaje; hodnota si zachová svůj vzhled, HTML, podtabulku i interakce. Hodí se například pro hodnotu, jejíž formátovací šablona již obsahuje vlastní popisek nebo ikonu. Parametr funguje s použitím sekcí i bez nich. Neovlivňuje štítek sloupce v hlavičce, který řídí showCaptionLabel.

Doplňující text a HTML pod náhledem

textInfo a htmlInfo přidají obsah pod údaje a všechny nástroje komponenty. Mohou být použity společně; jejich pořadí na stránce odpovídá pořadí parametrů v XML definici.

textInfo zobrazuje prostý text včetně nových řádků. Případné HTML značky vypíše jako text. Velikost a barva písma odpovídají štítkům hodnot, ve výchozích stylech 11 px a #666.

htmlInfo interpretuje HTML obdobně jako parametr content modifikátoru special.content.html. Jeho vzhled řídí vložené HTML a styly autora definice. HTML zapsané do atributu content je nutné escapovat jako XML:

<cxd:with-param name="textInfo" data-type="string"
                content="Před uzavřením zakázky zkontrolujte všechny údaje."/>
<cxd:with-param name="htmlInfo" data-type="string"
                content="&lt;p&gt;&lt;strong&gt;Upozornění:&lt;/strong&gt; Ověřte termín dodání.&lt;/p&gt;"/>

Obnova komponenty informační bloky nahradí aktuálním obsahem; nepřidává jejich další kopie.

Metody a události

Metoda	Volba v editoru	Význam
refresh	Obnovit obsah.	Znovu načte data a sestaví náhled, nástroje a informace. Znovu vyhodnotí také sections a noLabel.
reinit	Obnovit nastavení a obsah.	Před obnovením obsahu znovu načte vlastní nastavení náhledu, například šířku údajů nebo umístění nástrojů.
getColumnValue	Získat hodnotu sloupce.	Pro vstupní objekt s vlastností column vrátí aktuální textovou hodnotu sloupce bez HTML značek. Použijte název sloupce, například E10101976, bez prefixu $; pro neznámý sloupec vrátí prázdný řetězec.

Pro propojení jsou registrované události action (Použití akce) a edit (Úprava položky); z rozsahu položky také build (Vytvoření náhledu) a refresh (Obnovení obsahu). Událost build se vyvolá při sestavení náhledu, tedy i během obnovení. Společné události a metody komponent zůstávají dostupné podle jejich obecné registrace.