Tiskové šablony

1. Základní informace

• Tisk do tiskové šablony umožňují tlačítka umístěná v editačním formuláři nebo na nahlížecí stránce.
• Mezi podporované tiskové šablony patří soubory „xls“, „xlsx“, „doc“, „docx“, „html“, „txt“, „csv“ a „pdf“.
• NET Genium zpracuje také šablony „htm“, „xlsm“, „ods“, „docm“ a „odt“.
• Při načtení šablony „htm“ a „html“ se odstraní otevírací značka „<span style='display:none'>“ (obsah, který skrývala, se proto ve výstupu zobrazí) a mimo značku „<pre>“ se zalomení řádků (dvojice znaků CR a LF) nahradí mezerou a vícenásobné mezery se sloučí do jedné – řádkový komentář „//“ ve skriptu proto zakomentuje celý zbytek skriptu. Na začátek dokumentu se vloží styl, který odstavcům ruší okraje. Otevře-li se výsledek bez volby „Uložit jako PDF“ v novém okně prohlížeče, připojí se na konec skript, který vyvolá dialog tisku; do souboru odeslaného e-mailem, uloženého do přílohy nebo vytvořeného serverovou funkcí se skript nepřipojí.
• Tiskové šablony MS Excel, MS Word a „html“ podporují automatickou konverzi do „pdf“ volbou „Uložit jako PDF“ u tlačítka.
• Chybí-li soubor šablony, vytiskne se u šablon „txt“, „csv“ a „html“ prázdný dokument; u ostatních formátů a u šablony „html“ s volbou „Uložit jako PDF“ skončí tisk chybou.

2. Umístění a správa tiskových šablon

• Tiskové šablony musí být uloženy v adresáři „NETGenium\Templates“.
• Do tohoto adresáře je možné soubory nakopírovat napřímo z plochy serveru, nebo prostřednictvím dialogu pro nastavení NET Genia na záložce Tiskové šablony.
• Z těchto souborů je následně možné vybírat přímo ve vlastnostech tlačítka zvolenou tiskovou šablonu.

3. Identifikátory a proměnné v tiskových šablonách

• V tiskových šablonách se používají identifikátory databázových ovládacích prvků a skriptové proměnné. V šablonách „txt“, „csv“ a „html“ se navíc vyhodnocují serverové funkce a systémové proměnné; v šablonách MS Excel a MS Word ne. Vyhodnocují se jen funkce a proměnné zapsané v samotné šabloně – hodnoty dosazené ze záznamů a z proměnných se jako funkce ani proměnné nevyhodnotí, i když takový text obsahují. Funkce zapsaná v šabloně přitom takovou hodnotu dostane jako svůj argument; ani výsledek funkce se už jako funkce ani proměnná nevyhodnotí.
• Skriptové proměnné je možné naplnit před samotným tiskem pomocí skriptu.
• Na místo v šabloně, kam je potřeba dosadit hodnoty, se vkládají identifikátory databázových ovládacích prvků nebo názvy proměnných.
• NET Genium otevře tiskovou šablonu, vyhledá výskyty všech identifikátorů, a nahradí je příslušnými hodnotami.
• Detailní popis proměnných používaných v tiskových šablonách a možností formátování ovládacích prvků je uveden v samostatné příručce Proměnné.

3.1. Tisk z editačního formuláře

• Dosazení hodnot databázových ovládacích prvků do tiskové šablony z aktuálně otevřeného záznamu v editačním formuláři používá identifikátory ve zkráceném tvaru ve formátu „#ng_ovládací_prvek#“.
• Tlačítko s tiskem záznam před tiskem vždy uloží; neuloží ho jen v editačním formuláři pouze pro čtení.

3.2. Tisk z nahlížecích stránek a tabulek

• Vytisknou se všechny záznamy, které odpovídají podmínkám nahlížecí tabulky a hledání, filtrům a časovému úseku zadaným uživatelem, v jeho řazení – ne jen aktuálně zobrazená stránka. Označené záznamy se při tisku neberou v úvahu. Počet tištěných záznamů omezuje jen volba „Načíst pouze prvních“ databázového dotazu.
• Tisk záznamů nahlížecí tabulky vyžaduje používání identifikátorů v plném tvaru v následujících možných formátech:

3.2.1. První formát (doporučený)

• „#DG10#.#ng_ovládací_prvek#“, „#DG11#.#ng_ovládací_prvek#“, atd.
• Určený a nejvhodnější pro datagridy, používá zapisování pomocí ID datagridu (JavaScriptový název prvku).
• Tento způsob je stabilnější v případech, kdy se do formuláře přidávají další datagridy a mění se tak jejich pořadí, což by u druhého formátu vedlo ke změně identifikátoru.
• Číslo za písmeny „DG“ je ID ovládacího prvku nahlížecí tabulky.

3.2.2. Druhý formát

• „#datagrid1#.#ng_ovládací_prvek#“, „#datagrid2#.#ng_ovládací_prvek#“, atd.
• Formát plného identifikátoru s pojmenováním typu vizuálního ovládacího prvku a s číslem jeho pořadí zohledňuje situace, kdy je v editačním formuláři nebo na nahlížecí stránce umístěno více nahlížecích tabulek se stejným zdrojem dat, jen s různými omezujícími podmínkami.
• Další příklady:
  • „#calendar1#.#ng_ovládací_prvek#“, „#calendar2#.#ng_ovládací_prvek#“, atd.
  • „#timetable1#.#ng_ovládací_prvek#“, „#timetable2#.#ng_ovládací_prvek#“, atd.
  • „#planner1#.#ng_ovládací_prvek#“, „#planner2#.#ng_ovládací_prvek#“, atd.
  • „#kanban1#.#ng_ovládací_prvek#“, „#kanban2#.#ng_ovládací_prvek#“, atd.

3.2.3. Třetí formát

• „#ng_formulář#.#ng_ovládací_prvek#“.
• Šablony MS Word tento formát nerozpoznají – používají jen první a druhý formát.

3.2.4. Čtvrtý formát

• „#*#.#ng_ovládací_prvek#“.
• Použije se při tisku z editačního formuláře v šablonách „txt“, „csv“, „html“ a MS Excel a v šabloně MS Excel tištěné z nahlížecí stránky s volbou „1 záznam = 1 list“ také pro vnořené tabulky formuláře každého záznamu; nahlížecí tabulku neurčuje – obsahuje-li formulář více nahlížecích tabulek, používá se první nebo druhý formát.

3.3. Chování tisku při použití plných identifikátorů

• NET Genium rozpoznává výskyt identifikátorů v plném tvaru, a zajistí automatické vkládání hodnot jednotlivých záznamů pod sebe.
• Jsou-li identifikátory umístěny vedle sebe v jedné řádce, je výstupem tisku tabulka, kde má každý záznam tabulky svůj řádek v tiskové šabloně.
• Jsou-li identifikátory umístěny vedle sebe ve dvou řádcích, je výstupem tisku tabulka, kde se každý záznam tabulky skládá ze dvou řádek v tiskové šabloně.
• Opakovaný úsek se liší podle formátu šablony:
  • „html“ – opakuje se jen řádek tabulky („<tr>“), ve kterém identifikátory leží; identifikátory mimo řádek tabulky se neopakují,
  • „txt“ a „csv“ – opakuje se úsek po sobě jdoucích řádků s identifikátory,
  • MS Excel – opakuje se úsek po sobě jdoucích řádků listu,
  • MS Word – záznamy se pod sebe neopakují. Při tisku z editačního formuláře se hodnoty všech záznamů nahlížecí tabulky vloží do jednoho pole oddělené čárkou, nemá-li tlačítko zaškrtnuté pole „1 vnořený záznam = 1 list (XLS) / 1 dokument (DOC)“ – s ním se každý záznam nejbližší nahlížecí tabulky nebo kalendáře umístěného nad tlačítkem (není-li tabulka statistická) vytiskne do samostatného dokumentu a dokumenty se stáhnou jako archiv ZIP; při tisku z nahlížecí stránky se každý záznam vytiskne do samostatného dokumentu a dokumenty se stáhnou jako archiv ZIP.
• V šabloně MS Excel se při vyplnění nahlížecí tabulky, jejíž identifikátory list obsahuje, z listu odstraní každý řádek, jehož buňka v prvním sloupci obsahuje přesně text „remove“. Má-li tlačítko v poli „Vnořené záznamy“ zvolenou hodnotu „Vkládat nové řádky“, řádek se neodstraní, ale jeho první buňka se vyprázdní a řádek se skryje nastavením nulové výšky.

3.4. Specifické scénáře tisku

• Tisk z nahlížecí stránky, která obsahuje pouze jednu nahlížecí tabulku, nevyžaduje identifikátory v plném tvaru, stačí identifikátory ve zjednodušeném tvaru.
• Tisk z nahlížecí stránky do šablon „pdf“ a MS Word vytiskne každý záznam prvního prvku typu „DataGrid“, „Calendar“, „TimeTable“, „Planner“ nebo „Kanban“ do samostatného souboru; statistická nahlížecí tabulka se přeskočí. Soubory se stáhnou jako archiv ZIP.
• Obsahuje-li nahlížecí stránka dvě a více nahlížecích tabulek, všechny nad stejným editačním formulářem a žádnou statistickou, nemá-li tlačítko zaškrtnuté pole „1 záznam = 1 list“ a šablona MS Excel nepoužívá identifikátory prvního ani druhého formátu („#DG...#.“, „#datagrid...#.“, „#calendar...#.“), vytiskne se každá tabulka na samostatnou kopii listu.
• Tisk statistické nahlížecí tabulky s agregovanými sloupci používá identifikátory sloupců „c0“, „c1“, „c2“ atd., tj. podle jejich pořadí v hlavičce tabulky, s číslováním od nuly.

3.5. Formátování hodnot v tiskových šablonách

• Tiskové šablony vytvořené v aplikaci MS Word musí mít identifikátory umístěné v poli typu „MergeField“.
• Hodnoty mohou být v tiskové šabloně formátovány podle šablon pomocí syntaxe „#identifikátor@formát#“.
• V šablonách „csv“ se z hodnoty dosazené za identifikátor nebo proměnnou odstraní HTML značky, a obsahuje-li hodnota středník nebo zalomení řádku, nebo začíná či končí dvojitou uvozovkou, uzavře se do dvojitých uvozovek a dvojité uvozovky uvnitř se zdvojí. Identifikátory se proto v šabloně „csv“ do uvozovek neuzavírají.

4. Obrázky v tiskových šablonách ve formátu „html“

• Tiskové šablony ve formátu „html“ mohou obsahovat obrázky (typicky logo) vložené značkou „<img>“, a to jedním z následujících tří způsobů:
  • Obrázek vložený přímo do šablony jako „data URI“ v kódování base64, např. <img src="data:image/png;base64,..."> — šablona je soběstačná a obrázek se vytiskne při tisku do „html“ i při konverzi do „pdf“. Doporučený způsob.
  • Odkaz na přílohu NET Genia — obrázek se nahraje do NET Genia jako příloha a do šablony se vloží relativní adresa přílohy ve tvaru <img src="Download.aspx?..."> (bez adresy serveru). Při konverzi do „pdf“ vloží NET Genium obrázek do dokumentu automaticky; při tisku do „html“ načítá obrázek prohlížeč přihlášeného uživatele.
  • Absolutní adresa veřejně dostupného obrázku, např. <img src="https://www.example.com/logo.png">.
• Relativní odkazy na soubory v adresáři „NETGenium\Templates“, např. <img src="Templates/logo.png">, se při konverzi do „pdf“ nevyhodnocují a v NET Genium Online nefungují ani při tisku do „html“, protože adresář „Templates“ není v cloudu přístupný přes prohlížeč. Proto se používají výhradně tři výše uvedené způsoby.

5. Události po tisku

• Po úspěšném vytvoření tiskové sestavy se automaticky spouští externí funkce „NETGenium.OnAfterPrint“, ve které je možné ovlivnit jak název výsledného souboru, tak i obsah nebo formát souboru.
• Tiskne-li se každý záznam do samostatného souboru, volá se funkce pro každý záznam zvlášť. Chyba ve funkci tisk přeruší.

5.1. Práva a obsah vytištěného dokumentu

• Tisková šablona vytiskne každý identifikátor, který obsahuje – i hodnotu ovládacího prvku, na který tisknoucí uživatel nemá právo, nebo jehož hodnotu by kvůli nastavení „Zobrazit hodnotu“ na „Pouze vlastníkovi nebo spoluvlastníkovi záznamu“ neviděl. Obsah vytištěného dokumentu tak určuje autor šablony, nikoli oprávnění tisknoucího uživatele.
• Formátování hodnot (převod na zobrazovaný text, formát čísla a data) se uplatní jen u ovládacích prvků, na které má uživatel právo; ostatní identifikátory se vyplní hodnotou uloženou v databázi.

5.2. Kódování textových šablon

• Šablony „txt“, „csv“, „htm“ a „html“ uložené v kódování UTF-8 s BOM se vytisknou do souboru rovněž v UTF-8 s BOM. Šablony bez BOM se čtou i vytisknou ve znakové sadě serveru (typicky Windows-1250).

5.3. Název výsledného souboru

• Při tisku tlačítkem tvoří název výsledného souboru popisek tlačítka a přípona výsledného formátu; archiv ZIP s dokumenty „pdf“ vytištěnými z nahlížecí stránky dostane název podle posledního záznamu. Je-li popiskem tlačítka text „Tisk“ v kterémkoli jazyce NET Genia (bez ohledu na velikost písmen), použije se místo něj název editačního formuláře, resp. nahlížecí stránky, ze které se tiskne.
• Název naplánovaný ve skriptu tlačítka funkcí „SCHEDULEPRINTNAME“ nahradí popisek tlačítka.
• Tiskne-li se každý záznam do samostatného souboru, pojmenují se soubory „Záznam 1“, „Záznam 2“ atd.; čísla se zleva doplní nulami na stejný počet číslic.
• Název souboru lze změnit v externí funkci „NETGenium.OnAfterPrint“.

6. Řešení problémů

6.1. Tisk více prázdných stránek u šablon „xls“ a „xlsx“

• Tiskne-li se s tiskovou šablonou ve formátu „xls“ nebo „xlsx“ více prázdných stránek, znamená to, že se obsah šablony nevejde na šířku stránky a přebývající sloupce se tisknou na samostatné stránky.
• Řešení: v tiskové šabloně se nastaví měřítko tisku na 100 % a zmenší se okraje stránky tak, aby se tisk vešel na šířku jedné stránky. V případě potřeby se zmenší také velikost písma a šířky sloupců.

7. Vztah k další dokumentaci

• Detailní popis proměnných používaných v tiskových šablonách a možností formátování ovládacích prvků je uveden v samostatné příručce Proměnné.
• Detailní popis programování tiskových šablon ve formátu „pdf“ je uveden v samostatné příručce Programování tiskových šablon ve formátu PDF.