Templates

Informations

Author: David
License: FPDF

Description

This script adds templates to FPDF for building documents containing a large number of similar pages. Typically, when a PDF is built with many pages sharing the same layout while only text changes, it can prove useful to use a template which will be defined only once as a single object and will be included in each page requiring that layout.

A template is defined by an external file containing a subset of raw FPDF instructions. This approach brings several benefits:

If the page layout is rather sophisticated, including a set of instructions only once in the PDF file instead of having those present in each and every page will significantly reduce the overall file size. In the example provided, that size is divided by two when compared to a PDF produced the standard way.
Separating layout design from PHP programming may make life easier for teams in charge of authoring documents. Different people may be assigned to layout design on one hand and data management on the other hand. The first team will only manipulate FPDF instructions without PHP programming while the other team will focus on data without bothering with color, fonts, positions, etc.
Finally, a powerful anchor feature has also been added which further enhances this {development / design} separation. It ties data to anchor IDs defined in templates which specify either a set of text properties (color, position, font) or a set of column widths.

Template rules

Templates must contain a subset of the FPDF instructions available in the FPDF class being used. Namely, this subset includes the following instructions: Cell(), Image(), Line(), Ln(), Rect(), SetDrawColor(), SetFillColor(), SetFont(), SetFontSize(), SetLeftMargin(), SetLineWidth(), SetMargins(), SetRightMargin(), SetTextColor(), SetX(), SetXY(), SetY(), Text(), Write().
If the current PDF class integrates some extended instructions such as Rotate(), RoundedRect(), Circle() or Ellipse(), they are also available within templates.
It is not allowed to define links in templates.
A page may include zero, one or several templates. A template may be present in all or in only a subset of pages.
Every line starting with one of the characters [';', '/', '*'] is considered comment and ignored.

Anchor definition

To define a text anchor within a template, use SetTextProp() with the following arguments:

SetTextProp(string anchor_id, float x_pos, float y_pos, float width, float height, string font_family, string font style, float font_size)

To define a column anchor, use SetColumns() with the following arguments:

SetColumns(string anchor_id, float col00, float col01, float col02, ...,  float col18, float col19)

Caution: anchor IDs are cross-template which means that they should be unique for a given PDF. If two templates used in the same PDF have anchors with the same ID, the last one will take precedence. There is however a clear distinction between text and column anchors, which means that a text anchor and a column anchor can share the same ID.

The method to load a template is:

int LoadTemplate(string file_tpl [, boolean verbose])

file_tpl: file name containing the template.
verbose: boolean indicating if each processed instruction should be logged to stdout. Defaults to false.

If successful, this function returns a positive integer usable at a later stage by IncludeTemplate():

IncludeTemplate(int handle)

handle: handle returned by a previous call to LoadTemplate()

The method to output a text according to a set of properties defined in a template is:

array ApplyTextProperties(string anchor_id, string text])

anchor_id: anchor identifier specified in one of the templates previously loaded.
text: string containing the text to output. If empty, text properties are still applied (position, color, font).

If successful, the method returns an associative array with the following keys:

px  =>  X position (float)

py  =>  Y position (float)

ix  =>  width or delta_x (float)

iy  =>  height or delta_y (float)

fr  =>  text color - red component (int)

fg  =>  text color - green component (int)

fb  =>  text color - blue component (int)

fam =>  font family (string)

sty =>  font style (string)

siz =>  font size (float)

The method to retrieve an array of column widths associated with an anchor ID is:

array GetColumns(string anchor_id)

anchor_id: anchor identifier specified in one of the templates previously loaded.

If successful, this method returns an array containing the widths of up to 20 columns.