Variables para plantillas de documentos: sintaxis común y lista de todos los tipos
Los documentos que imprime Yunbit (ofertas, pedidos, facturas, albaranes, órdenes de compra, etiquetas…) se pintan con una plantilla: un fichero HTML, o ZPL y SBPL en las etiquetas para impresoras Zebra y SATO, con marcas que Yunbit cambia por los datos del documento. Cada empresa puede subir sus propias plantillas para que sus documentos salgan con su diseño.
Este artículo explica lo común a todas las plantillas: cómo se suben, cómo se escriben las variables, los bloques que se repiten, las condiciones y los textos traducidos. Cada tipo de documento tiene después su propio artículo con todas sus variables.
- Cómo se sube una plantilla
- Variables
- Bloques: lo que se repite
- Condiciones
- Textos traducidos
- Cuidado con las llaves en CSS, JavaScript, ZPL y SBPL
- Qué artículo mirar según el «Aplica a»
- Formato de los números de documento
- La serie «Variables para plantillas»
Cómo se sube una plantilla
Las plantillas se dan de alta en el gestor de Plantillas (perfil SETUP: Administrador de ventas > Propuestas > Elementos de propuestas > Plantillas). Lo explica Gestor de plantillas de documentos. Los campos que importan para el diseño:
| Campo | Para qué sirve |
|---|---|
| Aplica a | El tipo de documento. Decide en qué documento se puede usar la plantilla y qué variables tiene. La lista completa está más abajo. |
| ¿Es la plantilla por defecto para el metagrupo? | Si vale «Sí», es la que sale cuando el documento, el cliente o el tipo no tienen una plantilla elegida. Deja solo una por defecto para cada «Aplica a». |
| Antigua | Una plantilla marcada como antigua no se usa como plantilla por defecto. |
| Mostrar artículos ocultos | En ofertas y pedidos, saca también las líneas que están marcadas como ocultas. |
| Fichero de plantilla | El fichero .tpl con el diseño. |
| Imagen de logo/cabecera, de margen y de pie | Imágenes que la plantilla puede usar con sus variables (cada artículo dice cuáles). |
Las facturas son la excepción: su plantilla se configura en el Administrador de finanzas y se elige en la ficha del cliente. Lo explica Configurar plantillas de factura.
Qué plantilla se usa en cada documento (la del propio documento, la del cliente, la del tipo, la marcada por defecto o la estándar de Yunbit) depende del tipo de documento. Cada artículo de la serie lo explica en su apartado «Cómo se elige la plantilla».
Consejo: parte siempre de una plantilla que ya funcione (la estándar o una vuestra), cambia poco cada vez y prueba con la vista previa del documento.
Variables
Una variable se escribe entre llaves y Yunbit la cambia por su valor al pintar el documento:
<p>Oferta nº {offer_num}</p>
- Las mayúsculas cuentan.
{WAY_TO_PAY}y{way_to_pay}son dos variables distintas y pueden traer cosas distintas. Copia el nombre tal cual lo da el artículo del documento. - Una variable que no existe sale vacía, sin ningún aviso. Si algo no aparece, revisa primero el nombre.
- Formato. Los importes salen ya formateados (por ejemplo
1.234,50), normalmente sin símbolo de moneda; las fechas, ya escritas como fecha. Cada artículo dice el formato y si un importe lleva IVA o no. - Algunas variables traen HTML dentro (saltos de línea
<br>en direcciones, o la imagen<img>completa de un código de barras). Esas se escriben solas, no dentro de un atributo comosrc="…".
Bloques: lo que se repite
Las líneas de un documento, los recibos de una factura o las etiquetas de varios artículos se pintan con un bloque. Lo que pongas entre BEGIN y END se repite una vez por elemento:
<table>
<!-- BEGIN concepts -->
<tr><td>{concepts.PART_NUMBER}</td><td>{concepts.UNITS}</td><td>{concepts.COST}</td></tr>
<!-- END concepts -->
</table>
- Dentro del bloque, sus variables llevan delante el nombre del bloque y un punto:
{concepts.COST}. - Bloques dentro de bloques. Algunos documentos agrupan las líneas (por ejemplo, las líneas de la oferta dentro de cada bloque de la oferta). El
BEGINy elENDllevan solo el nombre corto, y las variables el camino completo:
<!-- BEGIN blocks -->
<h3>{blocks.NAME}</h3>
<!-- BEGIN concepts -->
<p>{blocks.concepts.TITLE}: {blocks.concepts.COST}</p>
<!-- END concepts -->
<!-- END blocks -->
- Cada vuelta de un bloque trae dos variables más:
S_ROW_COUNT, la posición empezando en 0, yS_NUM_ROWS, el número total de vueltas. Por ejemplo,{concepts.S_NUM_ROWS}. <!-- BEGINELSE -->, entre elBEGINy elEND, marca lo que se pinta cuando el bloque no tiene ningún elemento.- Las variables de fuera del bloque (el número de documento, el cliente) se pueden usar también dentro.
Condiciones
Para que algo salga solo en ciertos casos:
<!-- IF agentowner != '' -->
<p>Comercial: {agentowner}</p>
<!-- ELSE -->
<p>Sin comercial asignado</p>
<!-- ENDIF -->
- Se escribe
<!-- IF condición -->, y opcionalmente<!-- ELSEIF condición -->y<!-- ELSE -->, y se cierra siempre con<!-- ENDIF -->. Respeta las mayúsculas de IF, ELSE y ENDIF y deja un espacio después de<!--y antes de-->. - Dentro de la condición la variable va sin llaves:
IF TYPE == '1',IF concepts.UNITS > 0. - Comparaciones:
==,!=,>,<,>=,<=. Para unir condiciones:and,or, ynotdelante para negar. - Filas alternas:
<!-- IF concepts.S_ROW_COUNT is even -->(pares) ois odd(impares). - Cuidado al comparar importes: llegan formateados como texto (
0,00,1.234,50), así queIF total > 0puede no hacer lo que esperas. Compara con!= ''o usa la variable sin formato si el artículo del documento la da.
Textos traducidos
Para que un texto salga en el idioma del documento, usa el diccionario de Yunbit:
| Escribe | Sale |
|---|---|
{ydic_clave} | El texto de esa clave del diccionario en el idioma del documento. |
{ydics_clave} | El plural. |
{ydic_clave:u}, {ydic_clave:l}, {ydic_clave:c} | En mayúsculas, en minúsculas o con la primera letra en mayúscula. |
Si la clave no existe, sale vacío. Para dar de alta un texto nuevo en el diccionario, pídeselo a Yunbit.
Cuidado con las llaves en CSS, JavaScript, ZPL y SBPL
Yunbit cambia cualquier palabra entre llaves por una variable, también dentro de los estilos, del JavaScript o de los comandos de una etiqueta. Si no existe la variable, el texto desaparece:
var opciones = {};queda comovar opciones = ;y el script deja de funcionar. Escribe{ }, con un espacio dentro, o pon el JavaScript en un fichero aparte..caja{}(una regla vacía) se pierde. Las reglas normales, como.caja { color: red; }, no tienen problema, porque llevan espacios y dos puntos dentro.- En una etiqueta ZPL o SBPL, un texto fijo como
{ABC}desaparece.
Además, en las etiquetas:
- ZPL (Zebra): los caracteres
^y~en los datos (un nombre o una descripción) cortan el campo. Para las tildes y la ñ, pon^CI28al principio de la etiqueta. - SBPL (SATO): después de pintar la etiqueta, Yunbit cambia
^y<por el carácter de control de SATO y borra los>y los saltos de línea. No uses comentarios HTML ni esos caracteres como texto.
Qué artículo mirar según el «Aplica a»
Cada «Aplica a» tiene sus propias variables. Algunos tipos solo aparecen en las plataformas que tienen esa funcionalidad (alquiler, mantenimiento, viajes, homologación de vehículos…).
| «Aplica a» | Qué documento es | Variables en |
|---|---|---|
| Ofertas | La oferta de venta | Ofertas y propuestas |
| Ofertas alquiler | La oferta de alquiler | Ofertas y propuestas |
| Propuestas | La propuesta comercial | Ofertas y propuestas |
| Pedidos (u Órdenes) | El pedido de venta | Pedidos de venta |
| Pedidos alquiler | El pedido de alquiler | Pedidos de venta |
| Pedidos TPV | El ticket del TPV | Pedidos de venta |
| (en Finanzas) | La factura emitida y la proforma | Facturas |
| Albaranes | Albarán, albarán sin precios, packing list | Albaranes, packing list y justificantes de entrega |
| Albaranes de transferencia de stock | El albarán de un traspaso entre almacenes | Albaranes, packing list y justificantes de entrega |
| Justificantes de entrega | El justificante firmado de la entrega | Albaranes, packing list y justificantes de entrega |
| Órdenes de compra | El pedido al proveedor | Órdenes de compra |
| Etiquetas de artículos, (ZPL), (SBPL) | Etiqueta de artículo | Etiquetas de artículo y de ubicación |
| Etiquetas de artículo-ubicación, (ZPL) | Etiqueta de un artículo en su ubicación | Etiquetas de artículo y de ubicación |
| Etiquetas de ubicación de almacenes, (ZPL) | Etiqueta de una ubicación | Etiquetas de artículo y de ubicación |
| Artículos | La ficha imprimible del artículo | Etiquetas de artículo y de ubicación |
| Etiquetas de contenedores, (ZPL), (SBPL) | Etiqueta de palé, caja o contenedor | Etiquetas de contenedor y de lote |
| Etiquetas de lotes | Etiqueta de lote | Etiquetas de contenedor y de lote |
| Etiqueta de expedición, (ZPL), (SBPL) | Etiqueta de cada bulto de un envío | Etiqueta de expedición |
| Etiquetas de fabricación, (ZPL), (SBPL) | Etiqueta del artículo fabricado en cada fase | Etiquetas de fabricación |
| Intervenciones | Parte de la intervención | Intervenciones |
| Plantillas Intervenciones | Informes de la intervención | Informes de la intervención |
| RMA | La devolución | RMA (devoluciones) |
| Informe de fallo | Formulario e informe de fallo de un equipo | Informe de fallo |
| Aptitud RAS | Certificado de aptitud de un equipo | Aptitud RAS |
| Direcciones | Etiqueta de envío de una dirección | Etiqueta de dirección |
| Tarifas | La tarifa de precios | Tarifas |
| Mensaje regalo | Tarjeta de mensaje regalo (ZPL) | Mensaje regalo |
| DeCA (documentos de control) | Documento de control del transporte | DeCA: documento de control del transporte |
| Consentimiento de información - RGPD | Página de firma del consentimiento | Consentimiento RGPD |
| Expediente/… (homologación, ATP, medidas, pesos, garantía) y Hoja de recepción | Documentos del expediente de un vehículo | Expedientes de homologación de vehículos |
| Itinerarios | Itinerario del viaje (el contrato de viaje combinado todavía no tiene «Aplica a» propio) | Itinerarios y contratos de viaje combinado |
| Notas de gasto | La nota de gasto (y la evaluación del desempeño) | Notas de gasto |
| Albaranes de compra, Recepción, Solicitudes de viajes | Ningún documento usa todavía estas plantillas | — |
Formato de los números de documento
Esto no es una variable de plantilla, pero se configura parecido. En el contador de pedidos, ofertas, RMA, expediciones, albaranes, recogidas, paquetes y órdenes de compra puedes usar:
| Escribe | Sale |
|---|---|
{YY} | El año de creación con dos cifras. |
{YYYY} | El año de creación con cuatro cifras. |
{NNNNN} | El número correlativo, con tantas cifras como letras N pongas y ceros a la izquierda. |
{COMPANYNUMBER} | El número de cliente vinculado a la aplicación. |
{CLIENTREFNUMBER} | El número de cliente relacionado vinculado a la aplicación. |
La serie «Variables para plantillas»
- Variables para plantillas de documentos: sintaxis común y lista de todos los tipos
- Ofertas y propuestas
- Pedidos de venta
- Facturas
- Albaranes, packing list y justificantes de entrega
- Órdenes de compra
- RMA (devoluciones)
- Tarifas
- Etiquetas de artículo y de ubicación
- Etiquetas de contenedor y de lote
- Etiqueta de expedición
- Etiquetas de fabricación
- Etiqueta de dirección
- Mensaje regalo
- DeCA: documento de control del transporte
- Intervenciones
- Informes de la intervención
- Informe de fallo
- Aptitud RAS
- Expedientes de homologación de vehículos
- Itinerarios y contratos de viaje combinado
- Notas de gasto
- Consentimiento RGPD