Adding Templates
Use templates to consistently add page elements to multiple pages in a PDF document. Templates automatically add page elements to all pages in a document or section, including headers and footers. The DynamicPDF Core Suite for .NET includes three template classes, Template, EvenOddTemplate, and HeaderFooterTemplate. The Template class is parent to the EvenOddTemplate and HeaderFooterTemplate classes.
| Template Classes | Description |
|---|---|
| Template | The Template class adds page elements to all pages in a section or document. |
| EvenOddTemplate | The EvenOddTemplate class adds different page elements to even or odd pages to a section or document. |
| HeaderFooterTemplate | The HeaderFooterTemplate class adds elements to a page's header and/or footer. |
Using templates usually also involves sectioning a document. See the Document Sectioning topic for information on how to break a document into sections and apply a section template.
Note the reliance on relative positioning in most of the examples on this page. As of v12, all page elements now have a RelativeTo and IgnoreMargins property. By default, RelativeTo is TopLeft, while IgnoreMargins is False (the default behavior in previous versions). However, using the RelativeTo and IgnoreMargins properties, the default behavior can be changed to meet different needs. This flexibility is useful when working with other size pages and customizing alignment.
Template
A template applies page elements to every page in a document/section of a PDF. Create a Template class by adding page elements and then setting the template to the Document's Template property. All page elements within this template will then appear in the background of the other PDF content.
By default, a page sets both the document and section template if either have a template. Change this behaviour by setting a page's ApplyDocumentTemplate or ApplySectionTemplate property to False to disable the template for that individual page.
Properties
| Property | Description |
|---|---|
| Elements | Collection of page elements in a template that are applied to any page using that template. Add elements to a template by calling the Elements.Add method. |
Example
The following example creates a template containing two rectangles and an image. It then applies that template to the document using the document's Template property.
Document document = new();
Template tmp = new();
document.Pages.Add(new Page());
float hgt = document.Pages[0].Dimensions.Height;
float x = -document.Pages[0].Dimensions.LeftMargin;
float y = -document.Pages[0].Dimensions.TopMargin;
float wdt = document.Pages[0].Dimensions.Width;
tmp.Elements.Add(new Rectangle(x, y, wdt, hgt, RgbColor.LightSkyBlue, RgbColor.LightSkyBlue));
tmp.Elements.Add(new Rectangle(x, y, 20, hgt, RgbColor.Navy, RgbColor.Navy));
tmp.Elements.Add(new Image("DPDFLogo.png", x + 30, y + 5));
tmp.Elements.Add(new Label("Test.", 200, 300, 200, 0));
document.Template = tmp;
Dim doc As New Document()
Dim tmp As New Template()
doc.Pages.Add(New Page())
doc.Pages.Add(New Page())
Dim hgt As Single = doc.Pages(0).Dimensions.Height
Dim x As Single = -doc.Pages(0).Dimensions.LeftMargin
Dim y As Single = -doc.Pages(0).Dimensions.TopMargin
Dim wdt As Single = doc.Pages(0).Dimensions.Width
tmp.Elements.Add(New Rectangle(x, y, wdt, hgt, RgbColor.LightSkyBlue, RgbColor.LightSkyBlue))
tmp.Elements.Add(New Rectangle(x, y, 20, hgt, RgbColor.Navy, RgbColor.Navy))
tmp.Elements.Add(New Image("DPDFLogo.png", x + 30, y + 5))
tmp.Elements.Add(New Label("Test.", 200, 300, 200, 0))
doc.Template = tmp
Figure 1. Template applied to a one page document.
EvenOddTemplate
Use an EvenOddTemplate to apply a template to even and odd pages differently, depending on whether the template's elements were added to the EvenElements or OddElements collection.
Properties
| Property | Description |
|---|---|
| EvenElements | Collection containing page elements that will be applied by the template to even pages. |
| OddElements | Collection containing page elements that will be applied by the template to odd pages. |
Example
The following example illustrates an EvenOddTemplate where the template uses different page number labels, depending on if the page is odd or even.
Document document = new();
document.Pages.Add(new Page());
document.Pages.Add(new Page());
document.Pages.Add(new Page());
document.Pages.Add(new Page());
EvenOddTemplate tmp = new EvenOddTemplate();
tmp.EvenElements.Add(new PageNumberingLabel("%%SP%% John Doe", 0, 0, 512, 12, Font.Helvetica, 12, TextAlign.Left));
tmp.OddElements.Add(new PageNumberingLabel("The DynamicPDF Core Suite %%SP%%", 0, 0, 500, 12, Font.Helvetica, 12, TextAlign.Right));
document.Template = tmp;
Dim myDoc As New Document()
myDoc.Pages.Add(New Page())
myDoc.Pages.Add(New Page())
myDoc.Pages.Add(New Page())
myDoc.Pages.Add(New Page())
Dim tmp As New EvenOddTemplate()
tmp.EvenElements.Add(New PageNumberingLabel("%%SP%% John Doe", 0, 0, 512, 12, Font.Helvetica, 12, TextAlign.Left))
tmp.OddElements.Add(New PageNumberingLabel("The DynamicPDF Core Suite %%SP%%", 0, 0, 500, 12, Font.Helvetica, 12, TextAlign.Right))
myDoc.Template = tmp
Figure 2. EvenOddTemplate applied to a four page document.
StampTemplate Property
The Document.StampTemplate property gets or sets a Template object for a document where all the template's elements appear above the page content. Note that the property sets a Template instance and not one of the Template class's two child templates. The assigned Template, if an instance of one of the two child template classes, only inherits the properties from the Template class. All page elements within a template that was assigned to the StampTemplate property appear in the foreground of the PDF pages content.
The following example illustrates assigning a template to the StampTemplate property. The resulting PDF covers the page's content.
Document document = new();
StampTemplateExample.CreatePage(document);
Template tmp = new();
float hgt = document.Pages[0].Dimensions.Height/2;
float x = -document.Pages[0].Dimensions.LeftMargin;
float y = -document.Pages[0].Dimensions.TopMargin;
float wdt = document.Pages[0].Dimensions.Width;
tmp.Elements.Add(new Rectangle(x, y, wdt, hgt, RgbColor.LightSkyBlue, RgbColor.LightSkyBlue));
tmp.Elements.Add(new Rectangle(x, y, 20, hgt, RgbColor.Navy, RgbColor.Navy));
tmp.Elements.Add((new Image("DPDFLogo.png", x + 30, y + 5)));
tmp.Elements.Add(new Label("Test.", 200, 300, 200, 0, Font.Helvetica, 90, RgbColor.Red));
document.StampTemplate = tmp;
Dim doc As New Document()
StampTemplateExample.CreatePage(doc)
Dim tmp As New Template()
Dim hgt As Single = doc.Pages(0).Dimensions.Height / 2
Dim x As Single = -doc.Pages(0).Dimensions.LeftMargin
Dim y As Single = -doc.Pages(0).Dimensions.TopMargin
Dim wdt As Single = doc.Pages(0).Dimensions.Width
Dim rec As New Rectangle(x, y, 20, hgt)
rec.FillColor = RgbColor.Navy
rec.BorderColor = RgbColor.Navy
Dim bkRec As New Rectangle(x, y, wdt, hgt)
bkRec.FillColor = RgbColor.LightSkyBlue
bkRec.BorderColor = RgbColor.LightSkyBlue
tmp.Elements.Add(New Rectangle(x, y, wdt, hgt, RgbColor.LightSkyBlue, RgbColor.LightSkyBlue))
tmp.Elements.Add(New Rectangle(x, y, 20, hgt, RgbColor.Navy, RgbColor.Navy))
tmp.Elements.Add(New Image("DPDFLogo.png", x + 30, y + 5))
tmp.Elements.Add(New Label("Test.", 200, 300, 200, 0, Font.Helvetica, 90, RgbColor.Red))
doc.StampTemplate = tmp
Figure 3. Template applied to a document using the StampTemplate property.
HeaderFooterTemplate
A HeaderFooterTemplate places headers and footers for all pages in a document with different alignments (left, right, and center). It then places the header and footer text in the margin area of the page. However, page elements can also be added to this template that fall outside a document's header or footer. By default, the HeaderFooter template class aligns the header or footer text using center alignment. For left and right alignments, use the HeaderFooterText class.
Properties
| Property | Description |
|---|---|
| FooterCenter | Gets or sets the center footer text for the page. |
| FooterLeft | Gets or sets the left footer text for the page. |
| FooterRight | Gets or sets the right footer text for the page. |
| HeaderCenter | Gets or sets the center header footer text for the page. |
| HeaderLeft | Gets or sets the left header text for the page. |
| HeaderRight | Gets or sets the right header text for the page. |
Examples
The following three examples illustrate creating a HeaderFooterTemplate, creating a left-aligned PageNumberingLabel, and adding a HeaderFooterTemplate within an HTMLArea.
Header and Footer Text Example
The following example illustrates using a HeaderFooterTemplate. Notice the the HeaderFooterTemplate constructor sets the header and footer to the template's HeaderCenter. It then sets the template's left header text and then the template's bottom left foot text to the FooterCenter instances text, which was originally set in the HeaderFooter constructor.
Document document = new();
document.Pages.Add(new Page());
HeaderFooterTemplate header = new HeaderFooterTemplate("Header text", "Footer text");
HeaderFooterText leftText = new HeaderFooterText("Example Header");
header.HeaderLeft = leftText;
document.Template = header;
header.FooterLeft = header.FooterCenter;
Dim myDoc As New Document()
myDoc.Pages.Add(New Page())
Dim header As New HeaderFooterTemplate("Header text", "Footer text")
Dim leftText As New HeaderFooterText("Example Header")
leftText.Font = Font.Helvetica
leftText.FontSize = 12
header.HeaderLeft = leftText
myDoc.Template = header
header.FooterLeft = header.FooterCenter
Figure 4. A HeaderFooterTemplate applied to a PDF document.
PageNumberingLabel Example
This example illustrates creating a two right-aligned PageNumberingLabel instances. It then uses both in a HeaderFooterTemplate. The example requires positioning the page numbering labels manually.
The code used to create the document with five pages is omitted but you can view the full example on GitHub.
float x = document.Pages[0].Dimensions.Width - document.Pages[0].Dimensions.RightMargin * 2;
float y = -document.Pages[0].Dimensions.TopMargin/2;
HeaderFooterTemplate header = new HeaderFooterTemplate("OF", "Example Footer");
header.HeaderCenter.Font = Font.Helvetica;
header.HeaderCenter.FontSize = 14;
PageNumberingLabel pglb = new("PAGE %%CP%%", 0, y, 100, 50, Font.Helvetica, 14, TextAlign.Right);
pglb.IgnoreMargins = true;
pglb.VAlign = VAlign.Bottom;
header.Elements.Add(pglb);
PageNumberingLabel pglbRgt = new("%%TP%% PAGES", x, y, 100, 50, Font.Helvetica, 14, TextAlign.Right);
pglbRgt.X -= (pglb.Width/2);
pglbRgt.VAlign = VAlign.Bottom;
pglbRgt.IgnoreMargins = true;
header.Elements.Add(pglbRgt);
document.Template = header;
Dim myDoc As New Document()
DocumentExampleGenerator.Generate(myDoc)
Dim x As Single = myDoc.Pages(0).Dimensions.Width - myDoc.Pages(0).Dimensions.RightMargin * 2
Dim y As Single = -myDoc.Pages(0).Dimensions.TopMargin / 2
Dim header As New HeaderFooterTemplate("OF", "Example Footer")
header.HeaderCenter.Font = Font.Helvetica
header.HeaderCenter.FontSize = 14
Dim pglb As New PageNumberingLabel("PAGE %%CP%%", 0, y, 100, 50, Font.Helvetica, 14, TextAlign.Right)
pglb.IgnoreMargins = True
pglb.VAlign = VAlign.Bottom
header.Elements.Add(pglb)
Dim pglbRgt As New PageNumberingLabel("%%TP%% PAGES", x, y, 100, 50, Font.Helvetica, 14, TextAlign.Right)
pglbRgt.X -= (pglb.Width / 2)
pglbRgt.VAlign = VAlign.Bottom
pglbRgt.IgnoreMargins = True
header.Elements.Add(pglbRgt)
myDoc.Template = header
Figure 5. A HeaderFooterTemplate with two PageNumberingLabel instances applied to a PDF document.
Note the code creating the lines in Figure 5 were omitted from the example code, you can see the full example at GitHub.
HtmlArea in HeaderFooterTemplate Example
The following example illustrates using an HtmlArea in a HeaderFooterTemplate. This is a convenient way to add advanced formatting using HTML to a HeaderFooterTemplate. In this example, it creates an header with an image and background color by using an HtmlArea. It then adds a PageNumberingLabel to the header.
Document document = new();
document.Pages.Add(new Page());
float h = document.Pages[0].Dimensions.TopMargin;
float w = document.Pages[0].Dimensions.Width;
float x = document.Pages[0].Dimensions.Width - document.Pages[0].Dimensions.RightMargin * 2;
HeaderFooterTemplate header = new("HeaderText", "FooterText");
Uri filePath = new("example-header.html");
HtmlArea htmlArea = new(filePath, 0, 0, w, h);
htmlArea.IgnoreMargins = true;
header.Elements.Add(htmlArea);
PageNumberingLabel pglb = new("PAGE %%CP%% of %%TP%%", x, 0, 100, 50, Font.Helvetica, 14, TextAlign.Left);
pglb.IgnoreMargins = true;
pglb.VAlign = VAlign.Center;
header.Elements.Add(pglb);
document.Template = header;
Dim myDoc As New Document()
myDoc.Pages.Add(New Page())
Dim h As Single = myDoc.Pages(0).Dimensions.TopMargin
Dim w As Single = myDoc.Pages(0).Dimensions.Width
Dim x As Single = myDoc.Pages(0).Dimensions.Width - myDoc.Pages(0).Dimensions.RightMargin * 2
Dim header As New HeaderFooterTemplate("HeaderText", "FooterText")
Dim filePath As New Uri("example-header.html")
Dim htmlArea As New HtmlArea(filePath, 0, 0, w, h)
htmlArea.IgnoreMargins = True
header.Elements.Add(htmlArea)
Dim pglb As New PageNumberingLabel("PAGE %%CP%% of %%TP%%", x, 0, 100, 50, Font.Helvetica, 14, TextAlign.Left)
pglb.IgnoreMargins = True
pglb.VAlign = VAlign.Center
header.Elements.Add(pglb)
myDoc.Template = header
Figure 6. A HeaderFooterTemplate with an HtmlArea and a PageNumberingLabel applied to a PDF document.