🤖 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

(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}$; zolteka está 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 de PlantillaZolteka, el código no vale o ya lo usa otra clase, la descarta con un aviso en el log Zolteka.
  • 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, logo y pieDePagina también corren en listados y exportaciones de otros plugins, con el documento a null. $doc->documentoEnCurso() devuelve el documento o null.
  • base*() frente a pintar*(): 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() o pintarLogo(). Llamar a pintar<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): float pinta dentro de una transacción de Cpdf, mide cuánto baja y y 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.xml con un grupo cuyo name e id valen pdf-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 grupo zolteka_pdf. La plantilla aporta sus valores con valoresPorDefecto() y marca las casillas con clavesBooleanas().
  • Vista previa: el evento zpdf:actualizar permite que tu JavaScript retoque la maqueta de la pestaña con detail.plantilla, detail.valores, detail.hoja y detail.decorada(); una plantilla muy distinta puede devolver una maqueta propia en maquetaPreview().

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 el Translation/ 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 => texto para 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.

Cookies
Usamos cookies necesarias para el funcionamiento del sitio y cookies opcionales para recordar tus preferencias y mejorar tu experiencia. Puedes aceptarlas todas, rechazarlas o configurar tus preferencias

Soporte