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

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

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 žádný konkrétní záznam nepředává.

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.
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.
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; 0 při tisku z editačního formuláře.
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í:

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

Do archivního formátu se dokument převádí jen tehdy, když je na serveru v adresáři „Config“ instalace NET Genia uložen soubor „PDF_A_2A.txt“ a název souboru ve vlastnosti „FileName“ končí příponou „pdf“.

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 třemi 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"));

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.

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:

Používejte inline styly – 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 uložte 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ář umístěte ovládací prvek „Button“ a v jeho nastavení vyberte tiskovou šablonu „Faktura.pdf“.
Zkompilovanou knihovnu „ngef.dll“ nahrajte do adresáře „bin“ dané instance NET Genia.
Otevřete záznam a stiskněte tlačítko – NET Genium nabídne 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.