You are reading the documentation of the legacy and unsupported version 1 of FPDI.
For version 2 please refer to this documentation.
The FPDF_TPL Class An overview of the FPDF_TPL class
Table of Contents
Introduction
The class FPDF_TPL is an intermediate class between FPDF and FPDI. It builds the basis for reusing content within a PDF document through a technic called "form XObjects".
You can see this technic as a kind of template to which you can write and reuse it several times without re-writing its content by only referencing to it.
FPDF_TPL is the basis for FPDI but already comes with advantages beside preparing FPDF for FPDI:
- Data of templates are included in a PDF document only once
- Less memory usage
- Less generation time
- Smaller PDF files
- Recursive template support (use of templates in templates)
Examples of use (the greatest advantage of all is that a template has to be written to the PDF file only
once):
- Header generation for usage on several pages
- Grids for large tables over more pages
- Tableheaders
- Write behind or in front of a template
- Resize a template after creation
- ...
The methods of FPDF_TPL can only be used if the base class is FPDF. TCPDF comes with own template methods.
Usage
The logic of FPDF_TPL is very simple: You can start a template by calling beginTemplate(). All page content that is written with FPDF will be catched and encapsulated in the form XObject then.
Because a form XObject can be reused on several pages and/or sizes it is not possible to use dynamic content like links in templates. If you call such a method the error()-method will be called (before FPDI 1.5) or an Exception will be thrown (as of FPDI 1.5).
Following example will create a header template that will be re-used on every page then:
require_once('fpdf.php');
require_once('fpdf_tpl.php');
$pdf = new FPDF_TPL();
$pdf->AddPage();
$templateId = $pdf->beginTemplate();
$pdf->setFont('Helvetica');
$pdf->Text(10, 10, 'HEADING');
$pdf->endTemplate();
$pdf->useTemplate($templateId);
for ($i = 9; $i > 0; $i--) {
$pdf->AddPage();
$pdf->useTemplate($templateId);
}
$pdf->Output();
Methods
beginTemplate()
Description
Start a template.
This method starts a template. You can give own coordinates to build an own sized template. Pay attention, that the margins are adapted to the new template size. If you want to write outside the template, for example to build a clipped template, you have to set the margins and "cursor"-position manual after beginTemplate()-call.
If no parameter is given, the template uses the current page-size. The method returns an id of the current template. This id is used later for using this template. Warning: A created template is saved in the resulting PDF at all events. Also if you don't use it after creation!
Parameters
- $x : int
The x-coordinate given in user-unit
- $y : int
The y-coordinate given in user-unit
- $w : int
The width given in user-unit
- $h : int
The height given in user-unit
Return Values
The id of new created template
Exceptions
Throws LogicException
endTemplate()
Description
End template.
This method ends a template and reset initiated variables collected in beginTemplate().
Return Values
If a template is opened, the id is returned. If not a false is returned.
getTemplateSize()
Description
Get the calculated size of a template.
If one size is given, this method calculates the other one.
Parameters
- $tplIdx : int
A valid template-id
- $w : int
The width of the template
- $h : int
The height of the template
Return Values
The height and width of the template (array('w' => ..., 'h' => ...))
useTemplate()
Description
Use a template in current page or other template.
You can use a template in a page or in another template. You can give the used template a new size. All parameters are optional. The width or height is calculated automatically if one is given. If no parameter is given the origin size as defined in beginTemplate() method is used.
The calculated or used width and height are returned as an array.
Parameters
- $tplIdx : int
A valid template-id
- $x : int
The x-position
- $y : int
The y-position
- $w : int
The new width of the template
- $h : int
The new height of the template
Return Values
The height and width of the template (array('w' => ..., 'h' => ...))