Export dat z DataGridu

1. Základní informace

Export dat z DataGridu umožňuje uživatelům stáhnout data nahlížecí tabulky do souboru. Export se spouští ikonou v záhlaví nahlížecí tabulky a lze jej zakázat pomocí nastavení ovládacího prvku DataGrid. Detailní popis ovládacího prvku DataGrid je uveden v samostatné příručce Nahlížecí stránka - DataGrid nebo Editační formulář - DataGrid.

Podle typu nahlížecí tabulky probíhá export jedním ze tří způsobů:

• Řádková nahlížecí tabulka (na nahlížecí stránce i v editačním formuláři) a prvek History otevřou dialog exportu, ve kterém se volí formát a volby popsané v kapitolách 2 a 3.
• Statistická (agregační) nahlížecí tabulka, včetně statistického prvku LiteDataGrid, vyexportuje data bez dialogu rovnou do souboru XLSX – viz kapitola 4.
• Historie jednoho záznamu vyexportuje data bez dialogu rovnou do souboru XLSX – viz kapitola 5.

Export není dostupný v portletu, ve výběrovém dialogu (Picker), v panelu detailů, v prvku DataSet a u řádkového prvku LiteDataGrid.

1.1. Exportované záznamy

• Exportují se záznamy ze všech stránek nahlížecí tabulky, ne jen ze zobrazené stránky. Uplatní se podmínka databázového dotazu, časový úsek, filtry sloupců, složený filtr, hledaný výraz, řazení a nastavení „Načíst pouze prvních“.
• Označení záznamů zaškrtávacími poli export neomezuje.
• Je-li zaškrtnuté „Zobrazit pouze výsledky hledání“ a dotaz nemá nastavené „Načíst pouze prvních“, obsahuje export nejvýše jednu stránku výsledků; bez zadaného hledaného výrazu je export prázdný.
• Je-li nastavené „Načíst pouze prvních“ (a stejně tak v instanci bez platné licence, kde se načítá nejvýše 100 záznamů), nahlížecí tabulka nejprve načte daný počet záznamů a filtry sloupců a hledaný výraz uplatní až na ně. Export naopak nejprve vyfiltruje a teprve potom omezí počet záznamů. Při současném použití limitu a filtru nebo hledání proto může export obsahovat jiné záznamy, než zobrazuje nahlížecí tabulka.
• Je-li v databázovém dotazu nastavené „Odstranit záznamy s duplicitním“, duplicitní záznamy se odstraní i z exportu.

1.2. Exportované sloupce

• Bez volby „Všechny sloupce“ se exportují sloupce nahlížecí tabulky tak, jak si je uživatel přizpůsobil.
• S volbou „Všechny sloupce“ se exportují všechny databázové ovládací prvky zdrojové tabulky i tabulek připojených v dotazu, na které má uživatel právo, a navíc sloupce „(ID)“ a „(PID)“.
• Sloupce, jejichž hodnotu vidí jen vlastník nebo spoluvlastník záznamu, se neexportují nikdy.
• Hodnoty sloupců s heslem (identifikátor začínající „password“ nebo „md5“) se ve všech formátech nahradí znaky „*****“.

2. Formáty exportu

V dialogu exportu jsou nabídnuty tyto formáty:

2.1. Data (MS Excel)

• Výchozí formát při otevření dialogu exportu.
• Generuje soubor formátu Office Open XML (XLSX).
• V prvním řádku je název nahlížecí tabulky, pod ním hlavička sloupců. Hlavička používá zkrácený název ovládacího prvku, pokud je vyplněný.
• Datum se zapisuje jako datumová hodnota MS Excel, obsahuje-li čas, i s časem.
• Hodnoty šifrovaných sloupců TextArea a RichTextBox se nahradí znaky „*****“.
• Podporuje volbu zápatí se součty sloupců.
• Po úspěšném exportu spouští externí funkci „NETGenium.DataGrid2Excel“ s parametry: cesta k souboru, identifikátor dotazu ve tvaru „Q“ a ID dotazu, ID formuláře, datum od a datum do časového úseku nahlížecí tabulky.
• Pokud počet sloupců nebo řádků překročí limity definované v konfiguračních souborech „MaxExcelColumns.txt“ a „MaxExcelRows.txt“ umístěných v adresáři „Config“, export se automaticky přepne na formát CSV a externí funkce „NETGenium.DataGrid2Excel“ se nespustí.

2.2. Data (MS Excel 97-2003)

• Generuje soubor formátu BIFF8 (XLS).
• Obsah souboru je stejný jako u formátu XLSX, externí funkce „NETGenium.DataGrid2Excel“ se ale nespouští.
• Podléhá stejnému automatickému přepnutí na CSV jako formát XLSX v případě překročení limitů.

2.3. Data (CSV)

• Hodnoty jsou odděleny středníkem (;), řádky jsou ukončeny znaky CR LF.
• Kódování souboru je UTF-8 s BOM.
• Hlavička souboru obsahuje zkrácené názvy ovládacích prvků, pokud jsou vyplněné, jinak jejich názvy.
• Do uvozovek se uzavře jen hodnota, která obsahuje středník nebo konec řádku, nebo která uvozovkou začíná či končí; uvozovky uvnitř hodnoty se zdvojí.
• Datum se zapisuje ve formátu data uživatele včetně času se sekundami.
• Formát CSV je také cílový formát při automatickém přepnutí z XLSX nebo XLS.

2.4. Data (MS Word)

• Generuje soubor formátu Office Open XML (DOCX).
• Každý záznam je na samostatné stránce jako dvousloupcová tabulka – název sloupce a hodnota.

2.5. Data (MS Word 97-2003)

• Generuje soubor formátu DOC.
• Obsah souboru je stejný jako u formátu DOCX.

2.6. Data (HTML)

• Generuje soubor HTML obsahující data nahlížecí tabulky jako HTML tabulku.
• Hodnoty jsou před zápisem převedeny podle voleb exportu – cizí klíče, přílohy a HTML tagy.
• Hodnoty se do souboru zapisují tak, jak jsou uložené, bez kódování HTML znaků.

2.7. Data (TXT)

• Generuje textový soubor s daty nahlížecí tabulky jako tabulku se sloupci pevné šířky oddělenými znakem „|“.
• Hodnoty jsou před zápisem převedeny podle voleb exportu – cizí klíče, přílohy a HTML tagy.
• Kódování souboru je UTF-8.

2.8. Data (SQL)

• Generuje textový soubor se SQL příkazy.
• Pokud databázový dotaz nepoužívá spojení (JOIN), generují se INSERT příkazy pro každý řádek dat. Bez volby „Všechny sloupce“ obsahují příkazy sloupec „id“ a exportované sloupce nahlížecí tabulky, s volbou „Všechny sloupce“ všechny sloupce databázové tabulky.
• Pro každý sloupec s neprázdným databázovým názvem je vygenerován výpis ve formátu „sloupec = (hodnota1, hodnota2...)“ – jeden řádek na sloupec, hodnoty odděleny čárkou.
• Podporované datové typy hodnot: String (uvozovky), Integer, Long, Double, Date.
• Hodnota NULL je zapsána jako literál „NULL“.
• Kódování souboru je UTF-8.

2.9. Data (C#)

• Generuje textový soubor s C# kódem reprezentujícím data jako kolekci List<object[]>.
• Každý řádek dat je převeden na array.Add(new object[] { ... });.
• Podporované datové typy hodnot: String (escapované uvozovky), Integer, Long, Double, DateTime.
• Hodnota NULL je zapsána jako DBNull.Value.
• Výsledný soubor je uložen s příponou „txt“.
• Kódování souboru je UTF-8.

2.10. Přílohy (soubory/obrázky)

• Exportuje fyzické soubory příloh z exportovaných sloupců typu File a Image.
• Soubory jsou zabaleny do ZIP archivu.
• Název každého souboru v archivu je ve formátu: ID-{id záznamu}-{název sloupce}-{název souboru}.
• Z názvů souborů v archivu je automaticky odstraněna diakritika.
• Pokud žádný sloupec neobsahuje přílohy nebo všechny přílohy chybí na disku, export skončí chybou.

2.11. Data (XML)

• Generuje soubor XML se schématem.
• Obrázky vložené do hodnot prvku RichTextBox se vyexportují spolu s textem.
• Pro sloupce typu File a Image je přidán pomocný sloupec „{název sloupce} (Path + FileName)“ obsahující úplnou cestu k souboru na serveru a název souboru oddělené tabulátorem.
• Názvy sloupců v XML jsou upraveny tak, aby byly unikátní.
• ID záznamu obsahuje soubor jen s volbou „Všechny sloupce“.

2.12. Data + Přílohy (XML)

• Dostupné pouze pro uživatele s administrátorskými právy.
• Funguje stejně jako formát XML, ale pro sloupce typu File a Image přidává pomocný sloupec „{název sloupce} (Path + FileName + Base64)“ obsahující cestu k souboru, název souboru a Base64 obsah souboru, vše oddělené tabulátorem.
• Pokud soubor přílohy nelze přečíst, je Base64 část vynechána a sloupec obsahuje jen cestu a název.
• Výsledný soubor je uložen s příponou „xml“.

2.13. Data (JSON)

• Generuje soubor JSON s daty nahlížecí tabulky jako pole objektů.
• Obrázky vložené do hodnot prvku RichTextBox se vyexportují spolu s textem.
• Pro sloupce typu File a Image je přidán pomocný sloupec „{název sloupce} (Path + FileName)“ obsahující úplnou cestu k souboru na serveru a název souboru oddělené tabulátorem.
• Názvy sloupců v JSON jsou upraveny tak, aby byly unikátní.
• ID záznamu obsahuje soubor jen s volbou „Všechny sloupce“.
• Kódování souboru je UTF-8.

2.14. Data + Přílohy (JSON)

• Dostupné pouze pro uživatele s administrátorskými právy.
• Funguje stejně jako formát JSON, ale pro sloupce typu File a Image přidává pomocný sloupec „{název sloupce} (Path + FileName + Base64)“ obsahující cestu k souboru, název souboru a Base64 obsah souboru, vše oddělené tabulátorem.
• Pokud soubor přílohy nelze přečíst, je Base64 část vynechána a sloupec obsahuje jen cestu a název.
• Výsledný soubor je uložen s příponou „json“.

3. Možnosti exportu

V dialogu exportu jsou k dispozici tyto volby:

3.1. Všechny sloupce

• Pokud je zaškrtnuto, exportují se všechny sloupce popsané v kapitole 1.2, nejen sloupce aktuálně zobrazené v nahlížecí tabulce.
• U prvku History je tato volba vždy zapnutá a nelze ji měnit. U historie celého formuláře se exportují sloupce, které si uživatel v historii přizpůsobil.
• Pokud má nahlížecí tabulka zaškrtnuté „Zakázat uživatelské přizpůsobení“, tato volba je automaticky vypnutá bez ohledu na zadání uživatele.

3.2. Zakázat vyhodnocení externích funkcí

• Pokud je zaškrtnuto, nespustí se externí funkce „NETGenium.DataTable“, která smí načtená data upravit, a u skrytých textových polí jen ke čtení se nevyhodnotí hodnoty ve tvaru „ngef2(...)“.

3.3. Odstranit HTML tagy

• Pokud je zaškrtnuto, jsou z hodnot odstraněny HTML tagy před zápisem do výstupního souboru.
• Platí pro formáty: XLSX, XLS, CSV, HTML, TXT.
• Ve formátech XLSX a XLS navíc přeloží hodnoty prvků ComboBox, ListBox a Radio do jazyka uživatele a zaokrouhlí hodnoty typu Currency na dvě desetinná místa.

3.4. Cizí klíče jako celá čísla (bez textové hodnoty)

• Pokud je zaškrtnuto, jsou hodnoty sloupců s cizím klíčem (ForeignKey), které mají zaškrtnuté „Zobrazovat hodnotu v nahlížecí tabulce bez nutnosti joinování“, exportovány jako číselné identifikátory místo zobrazovaného textu. Ostatní cizí klíče se exportují jako číselné identifikátory vždy.

3.5. Přílohy jako celá čísla (bez názvu souboru)

• Pokud je zaškrtnuto, jsou hodnoty sloupců s přílohami (File a Image) exportovány jako číselné identifikátory místo názvů souborů.

3.6. Zobrazit součty sloupců

• Dostupné pro formáty XLSX a XLS.
• Pokud je zaškrtnuto, je do exportovaného souboru přidán řádek zápatí s agregovanými hodnotami (součty apod.) pro každý sloupec, u kterého zápatí není skryté. Řádek se přidá jen tehdy, obsahuje-li export více než jeden záznam.

4. Export statistické nahlížecí tabulky

• Ikona exportu stáhne data rovnou do souboru XLSX, bez dialogu exportu.
• Soubor obsahuje název nahlížecí tabulky, časový úsek a použité filtry, pod nimi data a vždy řádek součtů, i když ho nahlížecí tabulka nezobrazuje.
• Nastavení „Načíst pouze prvních“ omezí jen exportované řádky; součty zahrnují všechny řádky.
• Automatické přepnutí na formát CSV se neuplatní.
• Po exportu se spustí externí funkce „NETGenium.DataGrid2Excel“ se stejnými parametry jako u formátu XLSX.
• Export lze zakázat polem „Zakázat export dat“ statistické nahlížecí tabulky. U statistického prvku LiteDataGrid se toto pole v nastavení prvku nenabízí.

5. Export historie jednoho záznamu

• V historii změn jednoho záznamu stáhne ikona exportu data rovnou do souboru XLSX, bez dialogu exportu.
• Zákaz exportu se na tento export nevztahuje, automatické přepnutí na formát CSV se neuplatní a export se nezaznamenává do protokolu exportů.

6. Automatické přepnutí formátu

• Pokud je v dialogu exportu zvolen formát XLSX nebo XLS a zároveň platí alespoň jedna z podmínek:
  • Počet exportovaných sloupců překračuje limit definovaný v konfiguračním souboru „MaxExcelColumns.txt“ v adresáři „Config“.
  • Počet exportovaných řádků překračuje limit definovaný v konfiguračním souboru „MaxExcelRows.txt“ v adresáři „Config“.
• Dojde k automatickému přepnutí exportu na formát CSV.
• K přepnutí dochází před vygenerováním souboru.

7. Logování exportů

• Každý export z dialogu exportu a z dialogu „MS Excel Import/Export“ je zaznamenán do souboru „Export-{rok}-{měsíc}.log“ v adresáři „Logs“.
• Jsou zaznamenány dva záznamy: jeden po provedení databázového dotazu (s počtem řádků a textem dotazu), druhý po vygenerování souboru (s počtem řádků a názvem souboru).
• Zaznamenávají se: jméno uživatele, doba trvání operace, počet dotčených řádků, text dotazu nebo název vygenerovaného souboru.
• Export statistické nahlížecí tabulky se zaznamená jedním záznamem.

8. Bezpečnost

• Dialog exportu dostává databázový dotaz nahlížecí tabulky v zašifrované podobě, svázaný s nahlížecí tabulkou, ze které byl otevřen. Dotaz jiné nahlížecí tabulky dialog odmítne.
• Kontrola přihlášení a ochrany před Session Fixation probíhá při každém požadavku.
• Export lze zakázat na úrovni nahlížecí tabulky zaškrtnutím pole „Zakázat export dat“ v nastavení ovládacího prvku DataGrid. Zákaz se kontroluje i na serveru a nevztahuje se na uživatele s administrátorským oprávněním.
• Exportovat může i anonymní uživatel, pokud export není zakázaný.
• Formáty XML a JSON s Base64 obsahem příloh jsou dostupné výhradně uživatelům s administrátorskými právy; oprávnění se kontroluje i na serveru.
• Konfigurační soubor „DenyExport.txt“ v adresáři „Config“ se týká jen exportu aplikací, na export z nahlížecí tabulky nemá vliv.