Template Class

The Template class represents content which is repeated on each page of the PDF document. The templates can be used to create headers and footers, watermarks or any other content that needs to be repeated on each page of the PDF document.

A Template can render all the graphic elements (e.g HTML to PDF converter, texts, images, shapes) a PdfPage can render, but it cannot render interactive elements like PDF links, attachments, text notes. A Template class object can be instantiated using the Document.AddTemplate() method.

There two logical types of templates in HTML to PDF Converter: predefined templates (like header and footer) and custom templates. Both predefined and custom are instances of the Template class, but the predefined templates dimensions are for example considered when calculating the available client area in a PDF page.

Predefined Templates

The predefined templates are the document header and footer. The predefined templates are automatically docked to the corresponding side of the PDF page.

For example, the predefined header is automatically docked to the top of the PDF page which means the header location is the top left corner and the width of the header template is the width of the page. Also, if a predefined header was set, the available client area in PDF page will start right under the header. Similarly, if a predefined footer was set, it will be docked to the bottom of page and the available client area in PDF will end right above the footer template. It is recommended to set the predefined templates before starting to add elements to the document.

The HTML to PDF Converter API allows you to access the headers and footers for the PDF document created by the converter for customizations, but it doesn't allow you to change the header or footer template. The headers and footers can be created using the PdfConverter class interface.

Custom Templates

The custom templates can be used to add watermarks or any other content that must be repeated in the same position on each page. In the code sample below, a watermark containing text and an image is added to an existing document:

Copy

// get the first page the PDF document
PdfPage firstPage = document.Pages[0];

string logoImagePath = System.IO.Path.Combine(Server.MapPath("~"), @"img\logo.jpg");

// display image in the available space in page and with a auto determined height to keep the aspect ratio
ImageElement imageElement1 = new ImageElement(0, 0, logoImagePath);
AddElementResult addResult = firstPage.AddElement(imageElement1);

// add image border
// add a border to watermark
RectangleElement imageBorderRectangleElement = new RectangleElement(1, 1, addResult.EndPageBounds.Width,
                    addResult.EndPageBounds.Height);
firstPage.AddElement(imageBorderRectangleElement);

System.Drawing.Image logoImg = System.Drawing.Image.FromFile(logoImagePath);

// calculate the watermark location

System.Drawing.SizeF imageSizePx = logoImg.PhysicalDimension;

// transform from pixels to points
float imageWidthPoints = UnitsConverter.PixelsToPoints(imageSizePx.Width);
float imageHeightPoints = UnitsConverter.PixelsToPoints(imageSizePx.Height);

float watermarkXLocation = (firstPage.ClientRectangle.Width - imageWidthPoints)/2;
float watermarkYLocation = firstPage.ClientRectangle.Height / 4;

// add a template watermark to the document repeated on each document page
// the watermark size is equal to image size in points
Template watermarkTemplate = document.AddTemplate(new System.Drawing.RectangleF(watermarkXLocation, watermarkYLocation, 
        imageWidthPoints, imageHeightPoints + 20));

// add a standard font to the document
PdfFont watermarkTextFont = document.AddFont(StdFontBaseFamily.HelveticaBold);
watermarkTextFont.Size = 10;

// Add a text element to the watermark. You can add any other graphic element to a template
TextElement watermarkTextElement = new TextElement(3, 0, "This is Watermark Text", watermarkTextFont);
watermarkTextElement.ForeColor = System.Drawing.Color.Red;
watermarkTextElement.Transparency = 100;
watermarkTemplate.AddElement(watermarkTextElement);

// add an image to the watermak
ImageElement watermarkImageElement = new ImageElement(0, 20, logoImg);
watermarkImageElement.Transparency = 100;
watermarkTemplate.AddElement(watermarkImageElement);

// add a border to watermark
RectangleElement watermarkRectangleElement = new RectangleElement(0, 0, watermarkTemplate.ClientRectangle.Width, 
            watermarkTemplate.ClientRectangle.Height);
watermarkTemplate.AddElement(watermarkRectangleElement);

// dispose the image
logoImg.Dispose();

' get the first page the PDF document
Dim firstPage As PdfPage = document.Pages(0)

Dim logoImagePath As String = System.IO.Path.Combine(Server.MapPath("~"), "img\logo.jpg")

' display image in the available space in page and with a auto determined height to keep the aspect ratio
Dim imageElement1 As New ImageElement(0, 0, logoImagePath)
Dim addResult As AddElementResult = firstPage.AddElement(imageElement1)

' add image border
' add a border to watermark
Dim imageBorderRectangleElement As New RectangleElement(1, 1, addResult.EndPageBounds.Width, addResult.EndPageBounds.Height)
firstPage.AddElement(imageBorderRectangleElement)

Dim logoImg As System.Drawing.Image = System.Drawing.Image.FromFile(logoImagePath)

' calculate the watermark location

Dim imageSizePx As System.Drawing.SizeF = logoImg.PhysicalDimension

' transform from pixels to points
Dim imageWidthPoints As Single = UnitsConverter.PixelsToPoints(imageSizePx.Width)
Dim imageHeightPoints As Single = UnitsConverter.PixelsToPoints(imageSizePx.Height)

Dim watermarkXLocation As Single = (firstPage.ClientRectangle.Width - imageWidthPoints) / 2
Dim watermarkYLocation As Single = firstPage.ClientRectangle.Height / 4

' add a template watermark to the document repeated on each document page
' the watermark size is equal to image size in points
Dim watermarkTemplate As Template = document.AddTemplate(New System.Drawing.RectangleF(watermarkXLocation, watermarkYLocation, imageWidthPoints, imageHeightPoints + 20))

' add a standard font to the document
Dim watermarkTextFont As PdfFont = document.AddFont(StdFontBaseFamily.HelveticaBold)
watermarkTextFont.Size = 10

' Add a text element to the watermark. You can add any other graphic element to a template
Dim watermarkTextElement As New TextElement(3, 0, "This is Watermark Text", watermarkTextFont)
watermarkTextElement.ForeColor = System.Drawing.Color.Red
watermarkTextElement.Transparency = 100
watermarkTemplate.AddElement(watermarkTextElement)

' add an image to the watermak
Dim watermarkImageElement As New ImageElement(0, 20, logoImg)
watermarkImageElement.Transparency = 100
watermarkTemplate.AddElement(watermarkImageElement)

' add a border to watermark
Dim watermarkRectangleElement As New RectangleElement(0, 0, watermarkTemplate.ClientRectangle.Width, watermarkTemplate.ClientRectangle.Height)
watermarkTemplate.AddElement(watermarkRectangleElement)

' dispose the image
logoImg.Dispose()