Plantillas (XObjects)

Los Form XObjects de PDF — referidos como plantillas en TCPDF-Next — te permiten grabar un bloque de contenido una vez y estamparlo en cualquier número de páginas. Esto es ideal para encabezados, pies de página, marcas de agua, logos y cualquier elemento que se repita a lo largo del documento.

Todos los métodos retornan static, por lo que cada llamada puede ser encadenada (excepto startTemplate(), que retorna el ID de plantilla).

Referencia rápida

Método	Propósito
startTemplate()	Iniciar la grabación de una plantilla; retorna ID de plantilla
endTemplate()	Detener la grabación
printTemplate()	Colocar una plantilla grabada en la página actual

Ejemplo básico

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create();

// Crear una plantilla de encabezado reutilizable
$tpl = $pdf->startTemplate(190, 20);
$pdf->setFont('Helvetica', 'B', 14)
    ->setTextColor(255, 102, 0)
    ->cell(0, 10, 'ACME Corp — Confidential', align: 'C')
    ->line(0, 18, 190, 18);
$pdf->endTemplate();

// Usar la plantilla en múltiples páginas
$pdf->addPage()
    ->printTemplate($tpl, 10, 10)
    ->setFont('Helvetica', '', 12)
    ->setY(35)
    ->cell(0, 10, 'Page 1 content', newLine: true)

    ->addPage()
    ->printTemplate($tpl, 10, 10)
    ->setY(35)
    ->cell(0, 10, 'Page 2 content', newLine: true);

startTemplate()

$tpl = $pdf->startTemplate(float $w = 0, float $h = 0): int

Inicia la grabación de una nueva plantilla. Todas las operaciones de dibujo después de esta llamada se capturan en la plantilla en lugar de renderizarse directamente en una página.

Parámetro	Tipo	Descripción
$w	float	Ancho de la plantilla en unidades de usuario (0 = ancho de página)
$h	float	Alto de la plantilla en unidades de usuario (0 = alto de página)

Retorna un ID de plantilla entero usado para referenciar la plantilla posteriormente.

WARNING

No llames a addPage() mientras grabas una plantilla. Las plantillas capturan contenido dentro de un cuadro delimitador fijo — no son páginas.

endTemplate()

Detiene la grabación y finaliza la plantilla. El contenido dibujado después de esta llamada va a la página actual nuevamente.

printTemplate()

$pdf->printTemplate(int $id, float $x, float $y, float $w = 0, float $h = 0): static

Estampa una plantilla previamente grabada en la página actual en la posición especificada.

Parámetro	Tipo	Descripción
$id	int	ID de plantilla retornado por startTemplate()
$x	float	Posición X en la página
$y	float	Posición Y en la página
$w	float	Ancho de visualización (0 = ancho original de la plantilla)
$h	float	Alto de visualización (0 = alto original de la plantilla)

Puedes imprimir la misma plantilla a diferentes tamaños variando $w y $h. El contenido de la plantilla se escala para ajustarse.

Casos de uso

Encabezado / pie de página repetido

$header = $pdf->startTemplate(190, 15);
$pdf->setFont('Helvetica', 'B', 10)
    ->cell(95, 10, 'Company Name', align: 'L')
    ->cell(95, 10, date('Y-m-d'), align: 'R');
$pdf->endTemplate();

for ($i = 1; $i <= 5; $i++) {
    $pdf->addPage()
        ->printTemplate($header, 10, 10)
        ->setY(30)
        ->cell(0, 10, "Content for page {$i}", newLine: true);
}

Logo escalado

Imprimir la misma plantilla a diferentes tamaños:

$logo = $pdf->startTemplate(60, 20);
$pdf->image('/path/to/logo.png', 0, 0, 60, 20);
$pdf->endTemplate();

$pdf->addPage()
    ->printTemplate($logo, 10, 10, 60, 20)   // Tamaño completo
    ->printTemplate($logo, 10, 40, 30, 10);   // Mitad del tamaño

Consejos

• Las plantillas se almacenan como Form XObjects de PDF — el contenido se define una vez independientemente de cuántas veces se imprima, manteniendo el tamaño del archivo bajo.
• Las plantillas pueden contener cualquier contenido dibujable: texto, imágenes, formas e incluso otras plantillas.
• El sistema de coordenadas dentro de una plantilla comienza en (0, 0) en la esquina superior izquierda del cuadro delimitador.