Skip to main content
Version: Latest
Technical Manual

PDF documents

The PDF building block writes PDF files for every module that prints something: a certificate, a check, a pay statement, an invoice, a report export. It is two libraries, not a feature:

ProjectHolds
CrestApps.OrchardCore.Pdf.AbstractionsIPdfDocumentRenderer, the layout model in CrestApps.OrchardCore.Pdf.Models, PdfColor and PdfPageSize.
CrestApps.OrchardCore.Pdf.CoreThe renderer, the drawing primitives, fonts, text wrapping, images and QR codes, on PdfPig and QRCoder.

A module never references another PDF library: PdfLibraryLicenseTests bans the libraries whose licenses do not allow it. Never copy the drawing, font or text-wrapping code, and never draw a QR code as an image. Business Documents builds its receipts and invoices on this block, and Reports exports PDFs with it.

Positions and sizes are in points (72 to the inch) from the top left of the page, as a document is laid out.

A designed layout​

For a document whose design is data, such as a certificate template, describe the pages and hand them to IPdfDocumentRenderer:

services.AddPdfDocumentRenderer();

AddPdfDocumentRenderer() (Pdf.Core) registers the renderer once, however many modules call it. Then:

var fonts = PdfFontSet.GetInstalled("Noto Sans");
var page = new PdfPageLayout(PdfPageSize.Letter.Landscape);

page.Elements.Add(new PdfTextElement
{
Text = holderName,
X = 72,
Top = 200,
Width = 0,
FontSize = 32,
Bold = true,
Alignment = PdfTextAlignment.Center,
});

page.Elements.Add(new PdfQrCodeElement { Value = verificationUrl, X = 640, Top = 440, Size = 96 });

var layout = new PdfDocumentLayout
{
Title = "Certificate",
RegularFont = fonts.Regular,
BoldFont = fonts.Bold,
};

layout.Pages.Add(page);

byte[] pdf = renderer.Render(layout);

The layout model:

TypeWhat it is
PdfDocumentLayoutTitle and Author (the document information), RegularFont and BoldFont (TrueType files, embedded as a subset of the characters used; without a bold file the regular face is outlined), and the Pages.
PdfPageLayoutSize, an optional BackgroundColor, an optional BackgroundImage (a JPEG or 8-bit PNG stretched over the page, behind the elements) and the Elements, drawn in order so a later one is drawn over an earlier one.
PdfElementThe base of every element: X and Top.
PdfTextElementText on one line, or wrapped to Width (0 writes each line at X); FontSize, Bold, Color, Alignment (PdfTextAlignment: Left, Center, Right) and MaxLines (a longer text ends its last line with an ellipsis; 0 writes every line). Line breaks are kept, and a character the font has no glyph for is written as a question mark.
PdfImageElementA JPEG or 8-bit PNG (Data) stretched to Width by Height. A file of another kind is not drawn.
PdfLineElementA line from (X, Top) to (X2, Top2), with Color and Thickness.
PdfRectangleElementWidth by Height, with an optional Fill and an optional Outline of OutlineThickness.
PdfQrCodeElementA QR code holding Value, drawn as vector squares with its quiet zone on a white square, Size points wide, in Color.

PdfPageSize has Letter, Legal, A4, FromInches and Landscape (the same paper on its side). PdfColor has Black, White and FromRgb, TryParseHex for a stored brand color such as #1E3A8A, and TryParse and Parse for a color a designer typed.

The certificate template of Skills (CertificateDocumentBuilder) is built this way.

Documents that place or flow their own content​

When code lays a document out itself, use the primitives of Pdf.Core:

TypeUse
PdfDocumentWriterThe entry point for documents that place their content themselves, such as a check, a pay statement or a form: add the fonts, add a page, draw on it, and write the file.
PdfCanvasDraws on a page: text, lines, shapes and pictures at exact positions.
PdfFlowThe entry point for documents whose content flows from page to page, such as an invoice with any number of lines: it keeps the page being filled and the position on it, adds a page when the next block does not fit, and writes page numbers in the footers.
PdfFontSetThe regular and bold faces of an installed family. PdfFontSet.GetInstalled(family) finds the family, or the font that stands in for it (PdfFontResolver, which knows the file names on Windows, Linux and macOS).
PdfFontFaceOne face, measured and written with PdfPig.
PdfTextCleans a value (keeps its line breaks, turns other control characters into spaces) and wraps it to a width, between words and inside a word too long for the line.
PdfImageA PNG or JPEG with its size in pixels read from the file, to keep a logo's proportions.
PdfQrCodeEncodes a value with medium error correction and draws it as vector squares.

Fonts​

Every PDF embeds the font it is written in, so it looks the same everywhere. The font must be installed on the server. A site whose documents hold letters beyond Latin installs a family that has them, such as Noto Sans, and names it where the document lets you choose a font (the certificate template's Font, for one).