Guía completa: Personalizar Formatos de Impresión

¿Qué es y cómo funciona por dentro?

Cada documento que genera AdmCloud (una factura, una cotización, una orden de compra, una recepción, una acción de nómina, etc.) tiene un formato de impresión por defecto. Un formato de impresión personalizado te permite reemplazar ese diseño estándar por uno propio: escribes código HTML mezclado con Razor y AdmCloud lo convierte en el documento final, sustituyendo cada expresión por el dato real (cliente, líneas, totales, impuestos, datos de tu empresa, etc.).

El ciclo completo, de principio a fin, es el siguiente:

1. Asocias el formato a un tipo de documento (el campo Objeto). Ese tipo determina qué datos estarán disponibles: cada tipo de documento tiene su propio "modelo" de datos.
2. Escribes tu plantilla con HTML para el diseño y expresiones Razor (@Model.Propiedad) para insertar los datos.
3. La activas como formato por defecto de ese tipo de documento (en Formatos de Impresión por Defecto), a nivel de empresa o de sucursal.
4. Al imprimir o generar el PDF, AdmCloud carga el documento real, construye el modelo de datos correspondiente, compila tu plantilla reemplazando cada expresión por el valor real y produce el resultado: un PDF paginado o una sola página HTML.

Es distinto de los Formatos de Impresión de Cheques: aquellos posicionan datos sueltos por coordenadas sobre un cheque pre-impreso, mientras que un formato de impresión personalizado dibuja el documento completo (bordes, tablas, colores, imágenes) de principio a fin.

Lenguaje que soportan los formatos

Los formatos se escriben en HTML para la estructura y el estilo, combinado con Razor (la misma sintaxis de las vistas de ASP.NET, basada en C#) para insertar datos y aplicar lógica. En la práctica esto significa que puedes usar:

• Cualquier HTML y CSS que necesites: tablas, div, imágenes, estilos en línea o en una etiqueta <style>, tipografías, colores, etc.
• Expresiones de datos con @Model.Propiedad (por ejemplo @Model.CompanyInfo.CompanyName).
• Condicionales con @if (...) { ... } para mostrar u ocultar partes del documento.
• Ciclos con @foreach (var linea in Model.Header.Items) { ... } para recorrer las líneas del documento.
• Formato de valores con métodos de .NET, por ejemplo @Model.Header.DocDate.ToString("dd/MM/yyyy") o @valor.ToString("N2") para dos decimales.

Cómo crear un formato, paso a paso

1. Entra a Formatos de Impresión con HTML y usa el menú Nuevo desde Plantilla. Elige Vacío para empezar de cero, o selecciona un tipo de documento para partir de un diseño de ejemplo ya armado para ese documento (la lista solo muestra los documentos habilitados en tu plan).
2. En Nombre, dale un nombre único y descriptivo (por ejemplo, "Factura A4 con logo").
3. En Objeto, selecciona el tipo de documento al que aplica. Este campo define qué variables tendrás disponibles y qué datos de ejemplo verás en la vista previa. (Se oculta automáticamente si el formato se crea desde un Registro Personalizado.)
4. Elige el tipo de salida: activa PDF para un documento paginado (con márgenes y encabezado/pie repetidos en cada hoja), o déjalo desactivado para imprimir como una sola página HTML (típico de impresoras térmicas o matriciales).
5. En la pestaña Formato HTML, escribe tu plantilla. Apóyate en la plantilla de ejemplo más abajo y en el Diccionario de Datos para saber qué campos existen.
6. Revisa la vista previa en el panel derecho y corrige lo que haga falta.
7. Pulsa Guardar.
8. Actívalo en Formatos de Impresión por Defecto para el tipo de documento correspondiente. Hasta que no lo asignes ahí, el formato guardado no cambia lo que ven tus usuarios al imprimir.

Cómo se configura

Las variables del Model: cómo funcionan

El objeto Model representa el documento que estás imprimiendo. Accedes a sus datos con @Model. seguido del nombre de la propiedad. Muchas propiedades son objetos que a su vez tienen sus propias propiedades, así que encadenas con puntos: @Model.Relationship.Name (el nombre del cliente), @Model.CompanyInfo.CompanyName (la razón social de tu empresa), @Model.Header.DocDate (la fecha del documento).

Todos los tipos de documento comparten un grupo base de propiedades. Las más usadas:

Sobre esa base, cada tipo de documento agrega sus propias variables. Por ejemplo, una factura de venta suele tener Model.Terms (términos de pago), Model.SalesRep (vendedor), Model.Taxes (resumen de impuestos), Model.Currency (moneda) o Model.FiscalSequenceType (tipo de comprobante fiscal), mientras que un Pedido de Venta agrega Model.Stock (inventario disponible del artículo).

Ejemplo de plantilla

Este es un formato sencillo de una factura a crédito. Muestra el logo (o el nombre de la empresa si no hay logo), los datos del cliente y del comprobante, y recorre las líneas para armar la tabla:

<div class="factura">
    <header>
        @if (Model.Logo != null)
        {
            <img src="@Model.Logo.URI" alt="Logo" style="max-height:70px;" />
        }
        else
        {
            <h1>@Model.CompanyInfo.CompanyName</h1>
        }
        <p>RNC: @Model.CompanyInfo.TaxID</p>
    </header>

    <h2>@Model.Caption N° @Model.Header.Number</h2>
    <p>Cliente: @Model.Relationship.Name</p>
    <p>Fecha: @Model.Header.DocDate.ToString("dd/MM/yyyy")</p>

    @if (!string.IsNullOrEmpty(Model.FiscalSequenceType))
    {
        <p>Tipo de comprobante: @Model.FiscalSequenceType</p>
    }

    <table border="1" cellspacing="0" cellpadding="4" width="100%">
        <thead>
            <tr>
                <th>Artículo</th>
                <th>Cantidad</th>
                <th>Precio</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var linea in Model.Header.Items)
            {
                <tr>
                    <td>@linea.Item.Description</td>
                    <td align="right">@linea.Quantity</td>
                    <td align="right">@linea.Price.ToString("N2")</td>
                </tr>
            }
        </tbody>
    </table>
</div>

Y este sería un Pie de Página HTML típico del modo PDF, usando las variables especiales de paginación:

<div style="text-align:center; font-size:10px; color:#666;">
    Página {page} de {total-pages} &mdash; Impreso el {date} a las {time}
</div>

Dónde consultar las variables disponibles

Tienes dos formas de saber exactamente qué puedes usar en cada documento:

• Pestaña Diccionario de Datos (dentro del propio editor, cuando está habilitada para tu cuenta): al elegir el Objeto, muestra el nombre y el tipo de cada propiedad del documento, incluidas las listas (como las líneas) y los objetos anidados. Es la forma más cómoda porque la consultas sin salir de la pantalla de edición.
• Pantalla Variables HTML para Formatos de Impresión (dirección /PFDocumentation): una referencia independiente que documenta, documento por documento, cada campo, su descripción y su tipo de dato. Cuando un campo es un objeto o una lista, un enlace te lleva al Diccionario de Datos de esa tabla para ver sus campos internos (por ejemplo, Header.Items.Item.Description).

Cómo ver la vista previa

Mientras editas, el panel derecho muestra una vista previa en vivo del formato, renderizada con datos de ejemplo dentro de un recuadro aislado que no toca información real. Así puedes probar colores, tablas y textos con total libertad.

• La vista previa se genera al cargar la pantalla, al cambiar el Objeto y cada vez que pulsas el botón Actualizar.
• Usa el contenido actual del editor, no la versión guardada, para que veas al instante lo último que escribiste.
• Si tu código tiene un error de compilación, en lugar del diseño verás el mensaje de error, que te indica qué corregir.

Activar el formato y otras opciones

• Activarlo: un formato guardado no se usa solo. Debes asignarlo en Formatos de Impresión por Defecto, a nivel de empresa o de sucursal, para el tipo de documento correspondiente.
• Modificar con IA (si está disponible): con el botón Modificar con IA describes en español lo que quieres cambiar ("cambia el color principal a azul", "agranda el logo") y la IA reescribe el código; revísalo antes de guardar.
• Control de acceso: con Solo permitir acceso a la estructura al propietario restringes la edición y consulta del código solo al Propietario.
• Transferir a otra empresa que administras (requiere plan Enterprise con la función "Crear Plugins").

Consejos y errores comunes