Guía para editar plantillas de documentos de Holded (HTML)

Esta guía explica cómo personalizar el HTML de las plantillas de documentos de Holded (facturas, presupuestos, pedidos, albaranes…). Cubre la estructura de la plantilla, todas las variables disponibles, los bloques condicionales, las clases CSS que expone Holded y las particularidades del sistema que conviene conocer para obtener PDFs predecibles.

Cómo funciona el renderizado: tu HTML se rellena con los datos del documento y se convierte a PDF. El motor de renderizado admite un subconjunto de HTML/CSS — no es un navegador. La mayoría de sorpresas vienen de esperar comportamiento de navegador. Las reglas de esta guía te mantienen dentro de lo que el sistema renderiza de forma fiable.

1. Maqueta con tablas, no con flexbox ni grid. El sistema no admite display: flex, display: grid ni position: absolute/fixed. Toda maquetación en columnas debe hacerse con <table> / <tr> / <td> y anchos en porcentaje.

2. Un solo bloque <style> al inicio y estilos inline para lo específico. Mantén las reglas globales (fuentes, clases de items/totales) en el bloque de estilos; usa atributos style="…" en elementos concretos.

3. Usa <div> en lugar de <p>. El sistema aplica márgenes por defecto a <p> difíciles de controlar. <div> no añade espaciado inesperado.

4. Anchos en %, tamaños de fuente en pt. Los porcentajes fluyen bien en cualquier tamaño de papel; los puntos corresponden directamente al tamaño de impresión.

5. Añade width: 100%; table-layout: fixed a las tablas cuyas columnas deban respetar el ancho declarado. Sin table-layout: fixed, el sistema ajusta las columnas según su contenido y tus anchos se tratan como sugerencias.

6. Propiedad abreviada antes que la específica. Si combinas padding: 10px con padding-top: 4px en el mismo style, la abreviada debe ir primero — en orden inverso, la abreviada machaca el valor del lado. Igual con margin/border.

7. Los márgenes de página y las alturas de cabecera/pie se configuran en Holded, no en el HTML. El panel de configuración de la plantilla controla el área imprimible; tu HTML la rellena.

Estructura de página: cabecera, cuerpo y pie, con los márgenes configurados en Holded

Las cabeceras se repiten en cada página mediante bloques con nombre. El patrón estándar es una cabecera para la página 1 y otra para el resto:

• Las etiquetas de activación sethtmlpageheader son obligatorias — un bloque de cabecera sin ellas nunca se muestra.

• Si el contenido de la cabecera supera la altura configurada en Holded, se solapará con el cuerpo. Ajusta la altura en la configuración de la plantilla, no con CSS.

Un pie típico con contador de páginas:

• <pagebreak> es una etiqueta vacía — nunca escribas </pagebreak>. El contenido posterior empieza en una página nueva.

• Un patrón habitual es forzar los términos y condiciones a su propia página: coloca <pagebreak> justo antes del bloque [[TAC|…]].

Las variables usan la sintaxis %NOMBRE% y se sustituyen por los datos del documento al renderizar. Si un campo está vacío, la variable se sustituye por texto vacío (envuelve el contenido opcional en un condicional — sección 5 — para ocultar también su etiqueta).

Consejo de maquetación: como %ADDRESS% y %CLIENTADDRESS% se expanden a ~3 líneas, deja espacio vertical para ellas en las celdas de la cabecera. Usa %ADDRESSLINE% cuando necesites una sola línea compacta.

Se usan dentro del CSS como valores normales:

Los tokens {LANG_clave} muestran la etiqueta en el idioma del documento — úsalos en lugar de escribir "Factura" o "Invoice" a mano, para que una misma plantilla funcione en todos los idiomas.

Truco de mayúsculas: poner en mayúscula la clave pone en mayúscula el resultado — {LANG_invoice} → "factura", {LANG_Invoice} → "Factura".

Las claves más habituales están en las recetas de esta guía; la lista completa está al final, en el Extra.

Envuelve contenido en [[CONDICIÓN| … ]] y solo se mostrará cuando el documento tenga ese dato. Así evitas imprimir etiquetas vacías ("Vencimiento:" sin nada detrás).

Condiciones disponibles:

[[CUSTOMFIELDS|…]] repite su contenido una vez por cada campo personalizado; dentro, %CFK% es el nombre del campo y %CFV% su valor:

El token %ITEMS% se expande en una tabla con clase items. Se estiliza por completo desde tu bloque <style>.

Tabla de conceptos con los selectores de cabecera, cuerpo, columnas y líneas de título

Particularidad crítica de especificidad: el sistema ignora las reglas que apuntan solo a tr para el contenido de las celdas. .items tbody tr { border… } no tiene efecto visible — debes apuntar al td: .items tbody tr td { border… }. Ten en cuenta también que .items thead tr td (3 elementos) gana a .items tr td (2 elementos); apóyate en eso en lugar de usar !important.

Cada celda del cuerpo lleva además una clase de columna — el gancho más limpio para estilizar el contenido de una columna concreta:

Ejemplo — celdas de SKU e impuesto más grandes:

La alineación del texto por columna se controla con comentarios especiales colocados *dentro del bloque <style>* (Holded los lee aunque parezcan comentarios). th = celda de cabecera, td = celdas del cuerpo:

Nombres de columna válidos: name, desc, sku, photo, price, units, weight, totalweight, discount, subtotal, tax, total. Valores: left, center, right.

Valores por defecto si no los defines: las columnas de texto (name, desc, sku, photo) se alinean a la izquierda; las numéricas (price, units, discount, weight, totalweight, subtotal, tax, total) a la derecha.

Cuenta N solo sobre las columnas visibles, en su orden de visualización. Si defines anchos, defínelos en todas las columnas y haz que sumen 100%.

Los documentos pueden contener líneas de título que agrupan conceptos y muestran un subtotal acumulado (la suma de las líneas inferiores hasta la siguiente línea de título). Holded las muestra dentro de la tabla de conceptos con estos ganchos:

Particularidades:

• Las líneas de título se muestran en negrita por defecto (sin CSS; se puede anular con font-weight: normal en el selector de la fila).

• El subtotal muestra la suma de la columna Total; si Total está oculta, usa Subtotal; si ambas están ocultas, no se muestra ninguna suma.

• El borde interno entre la celda del título y la del subtotal nunca se dibuja — un border-right en el título o un border-left en el subtotal no aparecerán.

Coloca %TOTALSHTML% donde deba aparecer el desglose de totales. Para posicionarlo (p. ej. en la mitad derecha de la página), envuélvelo en una tabla:

Holded muestra uno de dos formatos según la configuración de la plantilla. Estiliza el que use tu plantilla:

Totales en formato vertical con los selectores de cada columna y de la fila TOTAL

Una tabla de 4 columnas (Base imponible | Impuesto | Total impuesto | Total) con una fila por tipo de impuesto y una fila final de suma.

Totales en formato desglose horizontal, con la primera columna invisible resaltada

Particularidades estructurales:

• La tabla tiene una primera columna invisible (<td class="firsttd">). Incluye siempre estas dos reglas para que nunca se vea:

• Debido a esa columna oculta, las reglas por columna van desplazadas una posición: las columnas visibles son td:nth-child(2) … td:nth-child(5).

• Para ocultar visualmente toda la fila de suma pero conservar el total final:

Las facturas sujetas a Verifactu deben mostrar el QR en la primera página. El bloque estándar, normalmente dentro de la cabecera firstpage:

• El QR se imprime a ~40×40 mm — reserva ese espacio en la maquetación de tu cabecera.

• Mantén centrado el contenido de la celda del QR; las etiquetas encima/debajo del QR las añade Holded.

• %LOGO% inserta la imagen del logo (ya envuelta para que la clase .logo le aplique). Controla el tamaño mediante la clase .logo.

• %SECIMG% inserta la imagen secundaria. Puedes envolverla en una etiqueta <img src="%SECIMG%"> con atributos width/height explícitos, o dejarla sin tamaño para usar el natural.

• Las imágenes externas por URL funcionan (<img src="https://…">), pero la URL debe ser accesible públicamente en el momento del renderizado.

• Prefiere los atributos HTML width/height en <img> frente a tamaños por CSS — el sistema los respeta con más fiabilidad.

• ❌ display: flex / grid / position: absolute — no compatibles. Usa tablas.

• ❌ Reglas CSS que apunten solo a tr para el contenido de las celdas — apunta a tr td.

• ❌ </pagebreak> — <pagebreak> es una etiqueta vacía, sin cierre.

• ❌ Fuentes web / @font-face — la tipografía viene de la configuración de la plantilla mediante %FONT%.

• ⚠️ <p> tiene márgenes por defecto — prefiere <div>.

• ⚠️ Los anchos de columna declarados solo se respetan con table-layout: fixed en la tabla.

• ⚠️ Abreviada + específica en el mismo estilo: la abreviada primero (padding: 10px; padding-top: 4px ✓ — al revés, se pierde silenciosamente el valor del lado).

• ⚠️ cellpadding="N" en una tabla funciona y rellena todas las celdas, pero el padding CSS por celda lo anula. El padding escrito directamente en cada <td> es lo más predecible.

• ⚠️ El contenido más alto que la altura configurada de cabecera/pie se solapa con el cuerpo — corrige la altura en la configuración de la plantilla en Holded.

• ⚠️ Las cadenas largas sin espacios pueden ensanchar una columna de tabla fija más de lo declarado; el sistema parte el texto en celdas fijas, pero pruébalo con datos reales.

• ⚠️ border-collapse: collapse va en la tabla, no en td/th (es una propiedad de tabla).

• ✅ Los atributos HTML clásicos (width="50%" en td, cellpadding, colspan, rowspan) están bien soportados y suelen ser más fiables que sus equivalentes CSS.

• ✅ Los atributos style inline están totalmente soportados y son la forma más segura de estilizar un elemento concreto.

Etiqueta + valor solo cuando hay dato:

Términos y condiciones en su propia página:

Cabecera a dos columnas (logo a la izquierda, datos de empresa a la derecha):

Bloque de datos del cliente:

Detalles del documento (número / fecha / vencimiento) en tabla:

Dirección de envío solo si existe:

Notas / observaciones al final del documento:

Campos personalizados en línea, uno por fila:

Tabla de conceptos con filas alternas (cebra):

Cabecera de la tabla de conceptos con fondo de marca y texto blanco:

Toda la tabla de conceptos con rejilla completa (estilo contable):

Padding uniforme en las celdas de una tabla de maquetación (con menos arriba):

Totales fijados a la mitad derecha:

Fila final del total (formato vertical) con línea superior y negrita:

Título del documento grande con el color de marca:

Pie con contador de páginas a la derecha:

Línea separadora fina entre secciones:

Espaciador vertical entre bloques:

Línea de título de la tabla de conceptos con fondo gris:

Se usan como {LANG_clave} (p. ej. {LANG_invoice}). Recuerda el truco de mayúsculas: {LANG_Invoice} → "Factura". Traducción al español mostrada como referencia; el sistema muestra el idioma del documento.

Cuando tengas dudas, mantén el marcado simple: tablas, divs y estilos inline — y prueba el PDF generado con un documento real que tenga notas, campos personalizados, dirección de envío y varios tipos de IVA, para ejercitar todos los caminos condicionales.