🤖 12.6. Estilo PDF
Cómo añadir plantillas de PDF para los documentos de Zolteka y variables propias para los nombres de archivo de los PDF.
Requisitos: Zolteka 2.30 o superior, FacturaScripts 2026.65 o superior y PHP 8.1 o superior. Cada apartado indica desde qué versión de Zolteka existe lo que describe; esta subpágina recoge hasta la 2.30.
📍 Esta es una subpágina de 12. Zolteka para desarrolladores. Antes de empezar, lee su apartado Antes de empezar: comprobar que Zolteka está activo y registrar en Init::init().
📍 En esta página:
- 12.6.1. Plantillas de PDF
- 12.6.2. Cabecera en todas las páginas
- 12.6.3. Variables propias en el nombre del PDF
12.6.1. Plantillas de PDF
(Desde la 2.29.) El motor sigue siendo el del núcleo. Una plantilla de PDF es una clase PHP que hereda de PlantillaZolteka y decide cómo se pinta cada bloque del documento; aparece en el selector «Plantilla del PDF» de Diseño → PDF. Lo que la plantilla no reescribe lo sigue haciendo Zolteka y, debajo, el núcleo: el QR de Verifactu, la dirección de envío, los recibos y los totales.
Los nueve bloques que puede reescribir son cabeceraEmpresa, logo, cabeceraDocumento, envio, lineas, pie, formaPago, recibos y pieDePagina. Cada uno recibe el eslabón de Zolteka ($doc) y, según el bloque, el documento. Por defecto llama a la base ($doc->baseCabeceraEmpresa(...), $doc->baseLineas(...)…).
Registro en el init() de tu plugin, sin consultas a la base de datos:
if (class_exists(PdfPlantillaRegistry::class)) {
PdfPlantillaRegistry::register(MiPlantilla::class);
}
- El código (
codigo()) cumple^[a-z][a-z0-9_]{0,29}$;zoltekaestá reservado para la base.nombre()devuelve la clave de traducción del nombre que sale en el selector. register()nunca lanza: si la clase no existe, no hereda dePlantillaZolteka, el código no vale o ya lo usa otra clase, la descarta con un aviso en el logZolteka.- Una plantilla guardada cuyo plugin se desactiva vuelve sola a la base. Se crea una instancia nueva por PDF: el constructor no recibe argumentos y la plantilla no guarda estado entre documentos.
- Los bloques
cabeceraEmpresa,logoypieDePaginatambién corren en listados y exportaciones de otros plugins, con el documento anull.$doc->documentoEnCurso()devuelve el documento onull. base*()frente apintar*():base<Bloque>()es «haz lo de siempre» dentro del mismo bloque. Para pintar la forma de pago, los recibos, el envío o el logo desde otro bloque reescrito, usa$doc->pintarFormaPago(),pintarRecibos(),pintarEnvio()opintarLogo(). Llamar apintar<Bloque>()desde ese mismo bloque es una recursión infinita.- Los nueve métodos
insert*del eslabón (Lib/PDF/PDFDocument.php) van sin tipo de retorno: void: si añades métodos al eslabón o los heredas, no se lo pongas. - El QR lo decide el núcleo (llega por los pipes de las extensiones). La plantilla solo decide dónde va y de qué tamaño (
pintarQr()). Por Verifactu debe medir entre 30 y 40 mm. - Ayudas de medida y color:
$doc->medirAlto(callable $pintar): floatpinta dentro de una transacción de Cpdf, mide cuánto bajayy lo rebobina;$doc->fondo(array $rgb, float $x, float $yArriba, float $ancho, float $alto)rellena un rectángulo detrás del texto; y$doc->conColorTexto(array $rgb, callable $pintar)fuerza un color de texto y lo restaura al terminar. - Opciones propias de la plantilla: un
Extension/XMLView/ConfigZoltekaPdf.xmlcon un grupo cuyonameeidvalenpdf-plantilla-CODIGO; Zolteka solo lo muestra cuando esa plantilla está elegida. Las claves de los campos llevan un prefijo propio y se guardan en el grupozolteka_pdf. La plantilla aporta sus valores convaloresPorDefecto()y marca las casillas conclavesBooleanas(). - Vista previa: el evento
zpdf:actualizarpermite que tu JavaScript retoque la maqueta de la pestaña condetail.plantilla,detail.valores,detail.hojaydetail.decorada(); una plantilla muy distinta puede devolver una maqueta propia enmaquetaPreview().
Ejemplo, banda de color de borde a borde detrás de la cabecera de empresa (bloque cabeceraEmpresa de una plantilla hija):
$alto = $doc->medirAlto(fn() => parent::cabeceraEmpresa($doc, $idempresa));
$pdf = $doc->lienzoPdf();
$doc->fondo($rgb, 0.0, (float)$pdf->ez['pageHeight'], (float)$pdf->ez['pageWidth'],
(float)$pdf->ez['pageHeight'] - (float)$pdf->y + $alto - $doc::MARGEN_TRAS_LOGO + 10.0);
$doc->conColorTexto($rgbTexto, fn() => parent::cabeceraEmpresa($doc, $idempresa));
💡 Tip Experto: el ejemplo es orientativo y no está garantizado entre versiones. Si tu plantilla reescribe un bloque, ese bloque pasa a ser tuyo: antes de darla por buena, prueba una factura con QR de Verifactu, con dirección de envío y con recibos.
12.6.2. Cabecera en todas las páginas
(Desde la 2.30.) Con la casilla «Repetir la cabecera en todas las páginas» (Diseño → PDF → «Cabecera y logo»), las páginas 2 y siguientes repiten lo que pinte el bloque cabeceraEmpresa de la plantilla. No hay un bloque nuevo ni tu plantilla tiene que hacer nada especial: se repite lo que dibuje cabeceraEmpresa(). Si la cabecera ocupa más de un tercio de la hoja, solo sale en la primera página.
12.6.3. Variables propias en el nombre del PDF
(Desde la 2.20; contrato ampliado en la 2.29.) Otro plugin puede añadir variables (por ejemplo {expediente}) a los patrones de «Nombres de PDF» sin tocar Zolteka. Implementa Lib/PdfNombre/PdfNombreVariableProviderInterface:
variables(): array:nombre => clave de traducción de su descripción. Esa clave va en elTranslation/de tu plugin y es la que sale en la tabla de ayuda.ejemplo(string $nombre): string: valor ficticio para la columna «Ejemplo» de la ayuda. No debe consultar la base de datos.valores(object $model, array $nombres): array:nombre => textopara ese documento. Solo recibe las variables tuyas que aparecen en el patrón.
Regístrala en el init() con PdfNombreVariableRegistry::register().
- El nombre de la variable cumple
^[a-z][a-z0-9_]{0,29}$y, como las propias, se escribe entre llaves, sin distinguir mayúsculas ni espacios. - Nunca pisa una variable propia de Zolteka. Un nombre no válido, uno que choca con una propia o uno sin clave de descripción se descarta con el aviso
zolteka-pdf-nombre-variable-ignorada; las demás variables del proveedor sí se registran. - Si
valores()lanza una excepción o devuelve algo que no es escalar, todas las variables de ese proveedor quedan vacías en ese documento.register()nunca lanza. - Los valores pasan por el mismo saneado que las variables propias.
- Vale en todos los sitios donde Zolteka pone el nombre: ficha, listado, email y el ZIP de «Exportar documentos».
use FacturaScripts\Plugins\Zolteka\Lib\PdfNombre\PdfNombreVariableProviderInterface;
class MiPluginVariableExpediente implements PdfNombreVariableProviderInterface
{
public function variables(): array
{
return ['expediente' => 'miplugin-var-expediente'];
}
public function ejemplo(string $nombre): string
{
return 'EXP-0042';
}
public function valores(object $model, array $nombres): array
{
$valor = $model->expediente ?? '';
return ['expediente' => is_scalar($valor) ? (string)$valor : ''];
}
}
use FacturaScripts\Plugins\MiPlugin\Lib\MiPluginVariableExpediente;
use FacturaScripts\Plugins\Zolteka\Lib\PdfNombre\PdfNombreVariableRegistry;
if (class_exists(PdfNombreVariableRegistry::class)) {
PdfNombreVariableRegistry::register(new MiPluginVariableExpediente());
}
Las Condiciones de uso de la página de entrada valen para esta subpágina, incluido el aviso de que los ejemplos de código son orientativos y se ofrecen sin garantía.