EN

Programování tiskových šablon ve formátu PDF

Hlavní stránka / Dokumentace / Příručka administrátora / Tiskové šablony /

Programování tiskových šablon ve formátu PDF

EN

1. Předmět a účel příručky

Tato příručka popisuje programování tiskových šablon ve formátu PDF pomocí externí funkce. Programová tisková šablona se používá tam, kde na vzhled dokumentu nestačí běžné tiskové šablony – typicky u faktur, nabídek a dalších dokumentů s přesnou grafickou úpravou, hlavičkovým papírem nebo vloženými přílohami.

Základní princip: dokument se navrhne jako HTML s inline styly a NET Genium se postará o převod do formátu PDF i o dokončovací práce – podložení hlavičkového papíru pod každou stránku, číslování stránek, značky pro přeložení dokumentu, vložení příloh do PDF a převod do archivního formátu PDF/A. Externí funkce proto nepotřebuje žádnou knihovnu pro tvorbu PDF.

Pro vytváření tiskových šablon ve formátu PDF je zapotřebí:

  • Projekt externích funkcí „ngef“ s referencí na knihovnu „NETGeniumConnection.dll“
  • NET Genium nainstalované na lokálním počítači

Detailní popis běžných tiskových šablon je uveden v samostatné příručce Tiskové šablony. Detailní popis externích funkcí je uveden v samostatné příručce Externí funkce.

2. Princip tisku přes externí funkci

  • V adresáři „Templates“ dané instance NET Genia je uložena tisková šablona s příponou „pdf“. Obsah tohoto souboru není podstatný – slouží jako výchozí dokument, který externí funkce přepíše.
  • Na editačním formuláři nebo nahlížecí stránce je tlačítko s nastavenou touto tiskovou šablonou.
  • Po stisknutí tlačítka NET Genium zkopíruje šablonu do dočasného souboru a zavolá externí funkci „NETGenium.OnAfterPrint“.
  • Externí funkce podle názvu šablony rozpozná, o jaký tisk se jedná, sestaví dokument a předá ho zpět NET Geniu.
  • NET Genium dokument dokončí a nabídne uživateli ke stažení.

Externí funkce „NETGenium.OnAfterPrint“ se spouští po tisku každé tiskové šablony dané instance, tedy i šablon ve formátech „txt“, „csv“, „html“, „xlsx“ nebo „docx“, těsně před odesláním souboru na klientskou stanici. Konkrétní tisk se rozpoznává podle názvu šablony v proměnné „conn.PrintingProcess.Template“.

Při tisku záznamu z editačního formuláře jsou v externí funkci k dispozici hodnoty tištěného záznamu standardním způsobem, např. „conn["ng_cislo"]“. Při tisku z nahlížecí stránky se tištěný záznam předává jen u šablon ve formátech Wordu a ve formátu „pdf“, u kterých se každý záznam tiskne do samostatného dokumentu; u ostatních formátů vrací conn["ng_cislo"] hodnotu null.

3. Objekt PrintingProcess

Aktuální tisk popisuje objekt „conn.PrintingProcess“ s těmito vlastnostmi:

  • FilePath – cesta k souboru, do kterého se tiskne. Co se na této cestě nachází po skončení tisku a dokončovacích prací, to NET Genium odešle uživateli. U šablon ve formátech „txt“, „csv“, „htm“ a „html“ je vlastnost null (s výjimkou dokumentu vytvářeného položkou „Nový ze šablony“) – výsledek tisku u nich určuje vlastnost „Content“, ze které se soubor zapíše až po návratu z funkce.
  • FileName – název souboru, který bude uživateli nabídnut ke stažení – možno změnit. Podle přípony NET Genium rozhoduje, zda jde o PDF – jen soubor s příponou „pdf“ se převádí do archivního formátu PDF/A.
  • Template – název tiskové šablony, podle kterého externí funkce rozpozná konkrétní tisk. Externí funkce volaná ze skriptu tlačítka, které tiskne do tiskové šablony, má objekt „conn.PrintingProcess“ k dispozici už před tiskem (vyplněné jsou jen vlastnosti „Template“, „Form“ a „ViewPage“) a přiřazením do vlastnosti „Template“ může vybrat jinou tiskovou šablonu.
  • Content – obsah tištěného souboru u šablon ve formátech „txt“, „csv“, „htm“ a „html“, tedy text šablony s nahrazenými proměnnými – možno změnit. U ostatních formátů je „null“ a jeho změna nemá žádný účinek.
  • Form – ID editačního formuláře, ze kterého byl tisk spuštěn; 0 při tisku z nahlížecí stránky.
  • ViewPage – ID nahlížecí stránky, ze které byl tisk spuštěn. Při tisku z editačního formuláře může obsahovat ID nahlížecí stránky, ze které byl formulář otevřen; tisk z editačního formuláře se proto rozpoznává podle nenulové vlastnosti „Form“.
  • SaveAs – způsob dokončení dokumentu. Pokud zůstane „null“, odešle se soubor na cestě „FilePath“ tak, jak je. Přiřazením objektu „SaveAsPdf“ se dokument dokončí jako PDF – viz následující kapitola.

4. Třída SaveAsPdf

Objekt „PrintingProcess.SaveAsPdf“ přiřazený do vlastnosti „conn.PrintingProcess.SaveAs“ říká NET Geniu, že má dokument dokončit jako PDF. Vlastnosti:

  • Html – HTML, které NET Genium převede do PDF. Pokud zůstane prázdné, žádný převod neproběhne a za hotové PDF se považuje soubor na cestě „FilePath“ – varianta pro externí funkce, které si PDF vytvářejí samy, viz kapitola 7.
  • MarginTop, MarginRight, MarginBottom, MarginLeft – okraje stránky v milimetrech; výchozí hodnota je 20 mm.
  • FooterHtml – HTML zápatí opakovaného na konci každé stránky. Zápatí se vykresluje jednou, proto nemůže obsahovat nic, co se mezi stránkami liší – číslování stránek patří do vlastnosti „PageNumbering“.
  • FooterHeight – výška místa vyhrazeného pro zápatí v milimetrech; zápatí s menším prostorem, než potřebuje, se ořízne.
  • PageNumbering – číslování stránek vkládané do pravého dolního rohu každé stránky. Znak „#“ zastupuje číslo aktuální stránky, „{0}“ celkový počet stránek – např. „Strana # / {0}“. Pokud zůstane prázdné, stránky se nečíslují.
  • BackgroundFilePath – cesta k PDF souboru, jehož první stránka se podloží pod každou stránku tištěného dokumentu – typicky hlavičkový papír. Podklad je vidět jen tam, kde dokument nechává stránku prázdnou.
  • FoldMarks – dvojice krátkých značek v levém a pravém okraji každé stránky, které ukazují, kde se má vytištěný dokument přeložit, aby se vešel do podlouhlé obálky (třetina výšky A4).
  • Attachments – soubory vložené do tištěného PDF, např. ISDOC faktury – viz kapitola 5.

Dokončovací práce probíhají v tomto pořadí:

  1. Převod „Html“ do PDF s použitím čtyř okrajů a zápatí
  2. Podložení „BackgroundFilePath“ pod každou stránku
  3. Vykreslení značek „FoldMarks“
  4. Vložení číslování stránek „PageNumbering“
  5. Vložení příloh „Attachments“
  6. Převod do archivního formátu PDF/A-2a, resp. PDF/A-3a při vložených přílohách; hybridní faktura Factur-X se převádí do PDF/A-3a, resp. PDF/A-3b

Do archivního formátu se dokument převádí jen tehdy, když je v instalaci NET Genia zapnutý převod do formátu PDF/A a název souboru ve vlastnosti „FileName“ končí příponou „pdf“. Výjimkou je hybridní faktura Factur-X (kapitola 5), která se do formátu PDF/A-3 převádí vždy, a tisková šablona „html“ s volbou „Uložit jako PDF“, která se při zapnutém převodu převádí bez ohledu na vlastnost „FileName“.

5. Přílohy vložené do PDF

Do tištěného PDF lze vložit libovolné soubory – typicky ISDOC faktury. Přílohy se přidávají do kolekce „Attachments“ a vytvářejí se čtyřmi způsoby:

// Soubor z disku, vložený pod vlastním názvem
pdf.Attachments.Add(new PrintingProcess.Attachment(filePath));

// Soubor z disku, vložený pod zadaným názvem
pdf.Attachments.Add(new PrintingProcess.Attachment(filePath, "Faktura.isdoc"));

// Obsah z paměti – dokument vytvořený externí funkcí se nemusí ukládat na disk
pdf.Attachments.Add(new PrintingProcess.Attachment(contentBytes, "Faktura.isdoc"));

// Strukturovaná faktura (objekt NETGenium.Finance.CII) – z PDF vznikne hybridní faktura Factur-X / ZUGFeRD
pdf.Attachments.Add(new PrintingProcess.Attachment(cii));

Soubor předaný cestou se načte do paměti okamžitě při vytvoření přílohy, takže nemusí na disku zůstat až do dokončení tisku.

Příloha vytvořená z objektu „NETGenium.Finance.CII“ (strukturovaná faktura) udělá z tištěného PDF hybridní fakturu Factur-X / ZUGFeRD: faktura se vloží jako soubor „factur-x.xml“ a dokument se vždy převede do formátu PDF/A-3 – do PDF/A-3a, jsou-li splněny podmínky převodu do archivního formátu z kapitoly 4, jinak do PDF/A-3b. Vedle ní lze vložit i další přílohy, např. ISDOC téže faktury; tištěný dokument ale smí nést jen jednu fakturu Factur-X, druhá ukončí tisk chybou.

6. Vzorová externí funkce

Externí funkce „NETGenium.OnAfterPrint“ se registruje ve třídě „ngef.cs“:

case "NETGenium.OnAfterPrint": Print.OnAfterPrint(args, conn); return "";

Vlastní tisková šablona pak vypadá například takto:

using NETGenium;
using System.Text;

namespace ExternalFunctions
{
  public class Print
  {
    public static void OnAfterPrint(string[] args, DbConnection conn)
    {
      if (conn.PrintingProcess.Template == "Faktura.pdf")
      {
        StringBuilder sb = new StringBuilder();

        sb.Append("<div style=\"font-family: Calibri; font-size: 10pt;\">");
        sb.Append("<h1>Faktura " + conn["ng_cislo"] + "</h1>");
        sb.Append("<p>Datum vystavení: " + conn.User.FormatDate(Parser.ToDateTime(conn["ng_datum"])) + "</p>");
        sb.Append("</div>");

        var pdf = new PrintingProcess.SaveAsPdf();

        pdf.Html = sb.ToString();
        pdf.FooterHtml = "<div style=\"font-family: Calibri; font-size: 8pt; text-align: center;\">www.firma.cz</div>";
        pdf.FooterHeight = 12;
        pdf.PageNumbering = "Strana # / {0}";

        conn.PrintingProcess.SaveAs = pdf;
        conn.PrintingProcess.FileName = "Faktura " + conn["ng_cislo"] + ".pdf";
      }
    }
  }
}

Doporučení pro sestavování HTML:

  • Styly se zapisují inline – dokument se převádí bez externích CSS souborů.
  • Stránka má formát A4; šířku obsahu určují okraje nastavené ve vlastnostech „MarginLeft“ a „MarginRight“.

7. Vlastní PDF bez převodu z HTML

Externí funkce si může PDF vytvořit i sama a zapsat ho přímo do souboru na cestě „conn.PrintingProcess.FilePath“. V takovém případě:

  • Pokud dokument nepotřebuje žádné dokončovací práce, vlastnost „SaveAs“ se nenastavuje.
  • Pokud má dokument dostat hlavičkový papír, číslování stránek, značky pro přeložení nebo přílohy, nastaví se vlastnost „SaveAs“ na objekt „SaveAsPdf“ s prázdnou vlastností „Html“ – za hotové PDF se pak považuje soubor na cestě „FilePath“ a provedou se na něm všechny ostatní dokončovací práce.

8. Vytvoření tiskové šablony a tlačítka v NET Geniu

  • Do adresáře „Templates“ dané instance NET Genia se uloží soubor tiskové šablony s příponou „pdf“, např. „Faktura.pdf“ – obsahem může být libovolné PDF, protože ho externí funkce při tisku přepíše.
  • Na editační formulář se umístí ovládací prvek „Button“ a v jeho nastavení se vybere tisková šablona „Faktura.pdf“.
  • Zkompilovaná knihovna „ngef.dll“ se nahraje do adresáře „bin“ dané instance NET Genia.
  • Po otevření záznamu a stisknutí tlačítka nabídne NET Genium hotový dokument ke stažení.

Detailní popis nastavení tlačítka je uveden v samostatných příručkách Editační formulář – Button a Nahlížecí stránka – Button.