The FPDF_TPL Class An overview of the FPDF_TPL class

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: 

PHP
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
public int FPDF_TPL::beginTemplate ( [ int $x = null [, int $y = null [, int $w = null [, int $h = null ]]]] )

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
public int|boolean FPDF_TPL::endTemplate ( void )

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
public array FPDF_TPL::getTemplateSize ( int $tplIdx [, int $w = 0 [, int $h = 0 ]] )

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
public array FPDF_TPL::useTemplate ( int $tplIdx [, int $x = null [, int $y = null [, int $w = 0 [, int $h = 0 ]]]] )

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' => ...))

Exceptions

Throws LogicException, InvalidArgumentException