Uso

¿A quién no le encantan los PDF, verdad? Las páginas web nativas están muy bien, pero al fin y al cabo, a veces se necesita un PDF para aquellos elementos que requieren la posibilidad de descargarse y guardarse. Por desgracia, crear PDF dinámicos sobre la marcha ha sido complicado, hasta ahora. Dado que los componentes de calidad para la conversión de HTML a PDF no son de código abierto, esta funcionalidad se ofrece en forma de complemento.

De hecho, este complemento no te ofrece una sola herramienta para crear archivos PDF, sino tres; sí, has leído bien… tres.

1. Bloque «Lava To PDF»: coloca este bloque en una página y podrás crear archivos PDF a partir de una sencilla plantilla de Lava.
2. Fusionar documentos PDF: Rock Core admite la fusión de documentos tanto en formato Word como HTML, ¡y ahora también puedes añadir el formato PDF a esa lista!
3. Acción de flujo de trabajo «Lava a PDF»: esta acción de flujo de trabajo toma una plantilla de Lava y crea un documento PDF que se almacena como un atributo.

Bloque «Lava To PDF»

Para crear un PDF, solo tienes que crear una nueva página y añadir el bloque «Lava To PDF» en ella. Indica una plantilla de Lava que genere un archivo HTML formateado y obtendrás un PDF. Así de sencillo. Pero espera, hay funciones, montones y montones de funciones…

Antes de profundizar en las funciones, veamos un detalle que te ayudará, como administrador, a dar formato a tu PDF. Si tienes acceso de administrador al bloque «Lava 2 PDF», no obtendrás el PDF directamente. En su lugar, se te mostrará un enlace al PDF. Si no ofreciéramos esta funcionalidad, básicamente no podrías editar tu PDF, ya que no podrías ver la configuración del bloque. Asegúrate también de utilizar la opción «Habilitar depuración» de la configuración del bloque para obtener una lista de los campos de fusión disponibles para su uso.

Configuración del bloque

A continuación se muestra una lista de los ajustes de bloque disponibles para la creación de documentos.

1. Comandos de Lava habilitados [Por defecto: Ninguno]
   1. Como no sabemos qué datos necesitarás para tu PDF, tendrás que utilizar los comandos de Lava para recuperar los datos directamente. Este bloque no sería tan útil sin estos comandos. Piénsalo un momento para hacerte una idea del potencial que tienes a tu disposición. Puedes generar documentos magníficos extrayendo datos de Rock mediante SQL o Rock Entities, puedes llamar a C# para obtener tus datos, o puedes realizar llamadas REST para extraer datos de sistemas de terceros. Esta última opción te dejará boquiabierto. ¡Imagina extraer datos de PCO y ofrecérselos a tus asistentes en la página web, personalizados exclusivamente para ellos!
2. Ancho del documento [Valor predeterminado: 8,5]
   1. No vamos a menospreciar tu inteligencia describiéndotelo. Solo tienes que saber que está en pulgadas y admite decimales.
3. Altura del documento [Valor predeterminado: 11]
   1. Tú puedes…
4. Nombre del documento [Por defecto: document.pdf]
   1. Este será el nombre del archivo cuando la persona lo descargue. También admite el formato «Lava», así que no hay motivo para usar «contribution-report.pdf» cuando se puede usar «contributions-ted-decker-2017.pdf».
5. Plantilla de documento [Default: <sample>]
   1. Esta es la plantilla HTML/Lava para crear tu documento. Asegúrate de leer detenidamente los consejos que aparecen a continuación a la hora de crear tu código HTML y CSS.
6. Abrir en línea [Por defecto: True]
   1. Esto determina cómo se abre el archivo en el navegador. Cuando la página se carga con el PDF integrado, el archivo PDF se mostrará en el navegador. Cuando se hace clic en el enlace con la opción de integración desactivada, el archivo PDF se descargará y la página que contiene el enlace permanecerá en el navegador. Es un efecto realmente genial, ya que nunca se ve la página que aloja el bloque «Lava To PDF».
7. Retraso en la visualización del documento [Valor predeterminado: 0]
   1. Esto establece un retraso (en segundos, sin decimales) que hay que esperar antes de generar el PDF. Esto resulta útil si necesitas esperar a que se descarguen fuentes externas o a que se ejecuten scripts (por ejemplo, al cargar Google Maps).
8. Creación automática de marcadores [Por defecto: False]
   1. Esto creará marcadores PDF a partir de las etiquetas h1-h6 de tu código HTML.
9. Activar depuración [Por defecto: False]
   1. Al igual que muchos de los bloques de Rock, cuenta con un modo de depuración que muestra los campos de fusión disponibles. Podrás acceder a elementos como: Atributos globales, Parámetros de página, Persona actual y Campus. También podrás ver el documento en un iFrame (sin el encabezado ni el pie de página).
10. Encabezado / Pie de página [Por defecto: desactivado]
    1. A continuación, hay una serie de ajustes relacionados con el encabezado y el pie de página. Los ajustes son los mismos para ambos, así que los describiremos juntos:
       1. Activar: si deben mostrarse
       2. Plantilla: la plantilla HTML de cada una. No se trata de documentos HTML completos. No tienen acceso a los estilos ni a los recursos de la plantilla de documento. Sin embargo, sí tienen acceso a Lava.
       3. Altura: es la altura (en pulgadas) del encabezado y el pie de página.
       4. Espaciado: es la altura (en pulgadas) del espacio que hay entre el encabezado o pie de página y el contenido del documento.
       5. Color de fondo: por supuesto, podrías configurarlo en tu plantilla, pero hemos incluido una opción para que te resulte un poco más fácil.

Consejos y trucos

A continuación te ofrecemos algunos consejos y trucos que te ayudarán a crear documentos con un aspecto GENIAL.

1. Aunque existe una opción para desactivar la repetición de los encabezados de las tablas cuando estas se extienden a más de una página, también puedes desactivarla en tu CSS tabla por tabla añadiendo style="display: table-row-group" a las etiquetas `thead` y `tfoot`.
2. Puedes forzar saltos de página en un PDF utilizando los atributos CSS «page-break-before:always» y «page-break-after:always» en los estilos de los elementos HTML. El atributo «page-break-before:always» forzará un salto de página justo antes de la posición en la página del PDF donde se mostraría normalmente el elemento, y el atributo «page-break-after:always» forzará un salto de página justo después de la posición en la página del PDF donde se mostraría normalmente el elemento.
3. Al configurar los márgenes de tu documento en CSS, no olvides que puedes utilizar pulgadas como unidad, por ejemplo: margin: 1in;
4. Si hay elementos `div` grandes u otros elementos que prefieras que no se dividan en un salto de página, utiliza «page-break-inside: avoid;» como propiedad de estilo. Si el motor de renderizado puede evitarlo, intentará no dividir el elemento.
5. Los enlaces internos del documento se mantendrán en el PDF.

Combinar documentos PDF

En general, los documentos de fusión de PDF funcionan de forma muy similar a sus homólogos en HTML. Sin embargo, en lugar de generar un documento HTML, la plantilla HTML se convierte en un PDF. La mayoría de los ajustes del bloque «Lava To PDF» anterior son compatibles con el documento de fusión. Dado que no hay ajustes del bloque que controlen estos parámetros, deberás añadirlos como parámetros en la etiqueta HTML de tu plantilla. A continuación se muestra un breve ejemplo que ilustra el uso de algunos de los parámetros (en verde). Más abajo encontrarás una lista completa de los mismos.

<html 
	document-width="11" 
	document-height="8.5" 
	document-name="mydocument.pdf"
	autogenerate-bookmarks="true"
	table-header-repeat-enabled="true"
	avoid-image-breaks="true"
	document-background-color="#c4c4c4;"
	image-scaling-enabled="false"
	reset-page-numbers-per-row="true" >
	<body>
	
		<header height="2" spacing=".1" background-color="#c80505">
			This is the header. Current Person = {{ CurrentPerson.FullName }}
		</header>
	
		{{ CurrentPerson.Full Name }}
	
		{% for row in Rows %}
			<pre>{{ row.FullName }}</pre>
		{% endfor %}
		
		<footer height=".5" spacing="2" >
			This is the footer. Current Person = {{ CurrentPerson.FullName }}
			<br>
			[page] of [topage];
		</footer>
	</body>
</html>

Cómo añadir encabezados y pies de página

You can add page headers and footers. To do this add <header> and <footer> tags to your document (as shown in blue in the example). These will be treated as page headers and footers (meaning they will show on each page).

El encabezado y los pies de página también tienen opciones de configuración.

¿Y qué hay de los comandos de Lava?

Dado que todos los usuarios del personal pueden subir sus propios documentos de fusión, no existe una forma segura de controlar el acceso a los comandos Lava específicos de un único documento de fusión. Al igual que su equivalente, la plantilla de fusión HTML de Core, las plantillas se basan en el atributo global «Comandos Lava habilitados por defecto» para obtener los comandos Lava habilitados.

Acción de flujo de trabajo «Lava a PDF»

En su forma más sencilla, esta acción del flujo de trabajo toma una plantilla HTML de Lava y la convierte en un archivo PDF, que se inserta en el atributo del flujo de trabajo que selecciones. Para poder utilizarlo, este atributo de resultado debe ser de tipo «Archivo».

A continuación se muestra un ejemplo muy sencillo de una plantilla y su PDF resultante.

Primero, los resultados (se ven mucho mejor así :) )

Y ahora, sin más preámbulos, la plantilla que se utilizó para crearlo.

1. Nombre del archivo: Tienes control total sobre el nombre del archivo que se utilizará para el PDF. Este campo admite incluso «Lava», para que puedas personalizarlo.
2. Atributo «Resultado»: es el atributo de archivo en el que se guardará el PDF.
3. Plantilla Lava: Por último, la plantilla HTML que se utiliza para determinar el contenido y el formato. A continuación, analizaremos algunas de sus funciones con más detalle.

Formato según el estilo

Vale, ya hemos visto un ejemplo y… ¡vaya, qué chulo! Pero… podemos hacerlo aún mejor… ¿no? Con el potencial del HTML y Lava, puedes dar rienda suelta a tu imaginación en el diseño. Echa un vistazo a esta plantilla y al resultado que ofrece.

Y ahora, la plantilla que da forma a esta obra de arte.

1. Antes de seguir adelante, vamos a asignar el atributo «person» del flujo de trabajo a una variable para poder hacer referencia a sus propiedades y atributos más adelante. Fíjate en que utilizamos el parámetro «Object» al cargar el atributo. Esto nos proporciona el objeto «person» completo (el valor por defecto nos daría el valor formateado, que es simplemente su nombre, ¡qué aburrido!).
2. Ten en cuenta que puedes incrustar fuentes personalizadas en tu PDF. Sin embargo, antes de hacer referencia a ellas, tendrás que indicar la ruta del archivo de fuente en tu CSS. Si estás familiarizado con la carga de fuentes personalizadas en CSS, verás que solo tenemos que registrar el archivo OTF o TTF. Unas líneas más abajo en el CSS verás que asignamos esta nueva fuente al elemento «body».
3. Puedes hacer referencia fácilmente a imágenes en tu plantilla. Fíjate en que el enlace a la imagen no incluye el nombre del servidor. La URL base para el HTML/CSS es la raíz interna de la aplicación, tal y como se define en los «Atributos globales». Por supuesto, si lo prefieres, puedes especificar la URL completa del enlace.
4. A continuación, añadimos otra imagen al documento. Esta vez, hacemos referencia a ella desde el objeto «person» (PhotoUrl). Ten en cuenta también que puedes utilizar todo tipo de CSS para modificar la imagen. ¡Hemos decidido darle un aspecto redondeado a la imagen y le hemos añadido un borde, solo por diversión!
5. Por último, mostramos algunos atributos del flujo de trabajo.

Recetas de uso

Bueno, ya hemos visto los tipos de documentos que podemos crear; ahora vamos a analizar algunos usos.

Una vez que el documento se haya almacenado en el atributo del flujo de trabajo, tienes varias opciones sobre qué puedes hacer con él. Considera estos ejemplos:

1. Atributo de persona: Mediante la acción «Conjunto de atributos de persona», puedes trasladar fácilmente el PDF del atributo de flujo de trabajo a un atributo de persona.
2. Atributo de miembro de grupo: Del mismo modo, también puedes utilizar la acción «Conjunto de atributos de miembro de grupo» para trasladar el PDF a un atributo de miembro de grupo.
3. Archivo de correo electrónico: Al enviar un correo electrónico, puedes incluir un enlace al archivo utilizando el Lava que aparece a continuación dentro de la acción «Enviar correo electrónico».

<a href="{{ 'Global' | Attribute:'ExternalApplicationRoot' }}GetFile.ashx?guid={{ Workflow | Attribute:'File','RawValue' }}">Download Receipt</a>

(Ten en cuenta que tendrás que actualizar la clave del atributo (marcada en verde) con tu valor específico)

Advertencias y consejos

Crear archivos PDF mediante esta acción del flujo de trabajo resulta increíblemente potente. Sin embargo, hay que tener en cuenta que estos archivos se almacenan como archivos binarios en Rock. Al configurar los atributos que los contienen, deberás asegurarte de seleccionar un «Tipo de archivo» que los guarde en una ubicación adecuada. Por lo general, esta no es la base de datos.

El almacenamiento en bases de datos es caro y las bases de datos de gran tamaño pueden resultar difíciles de copiar. En su lugar, podrías plantearte guardar los archivos en el sistema de archivos del servidor.

Deberás tener esto especialmente en cuenta al desarrollar el HTML/CSS de tu archivo. A menos que seas un genio (o tengas unos criterios de diseño poco exigentes), probablemente necesitarás varias pruebas para que tu archivo quede perfecto. No te gustaría nada tener que almacenar todos esos archivos en la base de datos (¡puaj!)

Además, ten en cuenta que el proveedor de almacenamiento que se utiliza para el archivo es el que se ha configurado mediante el «Tipo de archivo» del atributo del flujo de trabajo en el que se almacenó originalmente el PDF. Si trasladas este atributo del flujo de trabajo a un atributo de una persona o de un miembro de un grupo, el archivo binario base no se traslada, sino que solo se traslada el enlace al mismo. Asegúrate de seleccionar el «Tipo de archivo» adecuado al configurar el atributo del flujo de trabajo.

Encabezados y pies de página

Puedes añadir encabezados y pies de página a tus plantillas. Cada herramienta del kit de herramientas lo hace de una forma ligeramente diferente, así que asegúrate de leer más arriba cómo cada una de ellas implementa las plantillas de encabezado y pie de página. Las plantillas en sí mismas son estándar.

Each template is a snippet of HTML (do not add <html>, <head> or <body> tags). These snippets stand-alone from the primary content template, so you’ll need to re-implement any styling you’d like. These templates do support Lava so feel free to use it. They also support other dynamic arguments to support features like page numbering. Let’s look at that next.

Argumentos de la sección

Se pueden añadir los siguientes argumentos a tus encabezados y pies de página para incorporar funciones dinámicas, como los números de página.

• [página] - Se sustituye por el número de la página que se está imprimiendo en ese momento
• [frompage] - Se sustituye por el número de la primera página que se va a imprimir
• [topage] - Se sustituye por el número de la última página que se va a imprimir
• [página web] - Se sustituye por la URL de la página que se está imprimiendo
• [sección] - Se sustituye por el nombre de la sección actual
• [subsección] - Se sustituye por el nombre de la subsección actual
• [fecha] - Se sustituye por la fecha actual en el formato local del sistema
• [isodate] - Se sustituye por la fecha actual en formato ampliado ISO 8601
• [hora] - Se sustituye por la hora actual en el formato local del sistema
• [título] - Se sustituye por el título del objeto de la página actual
• [doctitle] - Se sustituye por el título del documento resultante
• [sitepage] - Se sustituye por el número de la página del sitio actual que se está convirtiendo
• [sitepages] - Se sustituye por el número de páginas del sitio actual que se está convirtiendo

Espaciado entre el encabezado y el pie de página

El funcionamiento de los encabezados y pies de página en relación con los márgenes y el contenido de la página puede resultar un poco confuso al principio. La siguiente figura muestra el diseño básico.

El espaciado entre el encabezado y los pies de página no es una ciencia exacta. Por ejemplo, si no dejas suficiente espacio en la altura del encabezado, este empezará a restar espacio al margen superior. Cuando se quede sin espacio en el margen, empezará a quedar recortado fuera de la página. Del mismo modo, te conviene ajustar el espaciado del encabezado y los pies de página para asegurarte de que no se solapen con el contenido. Si el encabezado o el pie de página empiezan a solaparse, basta con añadir más espacio.

Actualización desde la versión 1.0

Al actualizar la biblioteca a la versión 2.0, tuvimos que cambiar de biblioteca de PDF. Esto se hizo principalmente para dar soporte a quienes ejecutan Rock en Azure App Services. La nueva biblioteca también es mucho más rápida que la anterior y consume menos recursos del sistema. Así que hay algo para todos.

El cambio más importante tiene que ver con el funcionamiento de los encabezados y los pies de página. Consulta la sección «Encabezados y pies de página» para obtener toda la información.

Configuración de bloques de «Lava to PDF» que ya no existen

La nueva biblioteca PDF no admite todos los ajustes de la anterior. A continuación se indican algunos de los ajustes que no se han incluido. En la mayoría de los casos, existe una buena solución alternativa para conseguir el mismo resultado. En general, no te perderás gran cosa y ganarás mucho más a cambio.

El nuevo motor de renderizado es un poco diferente al de la versión 1.0. Por ejemplo, al utilizar columnas de Bootstrap, asegúrate de usar el punto de ruptura -xs- en lugar del habitual -md-.

Correcto: col-xs-6 Incorrecto: col-md-6

Ahora, ¡sal ahí fuera, soldado!

¡Basta de charla, sal ahí fuera y pon en marcha tu ministerio con esta nueva arma en tu arsenal!

Pero antes de hacerlo… te dejo una sorpresa más. A continuación encontrarás una plantilla sencilla de Lava para un informe de contribuciones. En realidad, es más bien un punto de partida, pero contiene la información básica que te interesa.

{% assign currentYear = 'Now' | Date:'yyyy' %}
{% assign selectedYear = currentYear %}


{% assign queryParms = 'Global' | Page:'QueryString'  %}
{% for item in queryParms %}
    {% assign kvItem = item | PropertyToKeyValue %}
    {% if kvItem.Key == 'Year' %}
        {% assign selectedYear = kvItem.Value %}
    {% endif %}
{% endfor %}

{% assign startDate = '1/1/' | Append:selectedYear %}
{% assign endDate = '12/31/' | Append:selectedYear %}

{% if currentYear == selectedYear %}
    {% assign endDate = 'Now' | Date:'M/d/yyyy' %}
{% endif %}


<html>
    <head>
        <style>
            body {
                font-family: Arial, Helvetica, sans-serif;
                font-size: 14px;
                padding: .5in;
            }
            table tr td, 
            table tr th {
                page-break-inside: avoid;
            }
        </style>
        <!-- Note: You may need to edit this URL to match your environment -->
        <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css"> 
    </head>
    <body>
        
        <div class="row">
            <div class="col-md-6">
                <strong>{{ 'Global' | Attribute:'OrganizationName' }}</strong><br />
                {{ 'Global' | Attribute:'OrganizationAddress' }}<br />
                {{ 'Global' | Attribute:'OrganizationWebsite' }}
            </div>
            <div class="col-md-6 text-right">
                <h4>Charitable Contributions for the Year {{ selectedYear }}</h4>
                <p>{{ startDate }} - {{ endDate }}<p>
            </div>
        </div>
        
        <h4 style="margin-bottom: 24px;">
            {{ CurrentPerson.FirstName }} {{ CurrentPerson.LastName }}<br />
            {{ CurrentPerson | Address:'Mailing','[[Street1]]' }}<br />
            {% assign address2 = CurrentPerson | Address:'Mailing','[[Street2]]' %}
            {% if address2 != '' %}
                {{ address2 }} <br />
            {% endif %}
            {{ CurrentPerson | Address:'Mailing','[[City]], [[State]] [[PostalCode]]' }}
        </h4>
        
        <table class="table">
            <thead>
                <tr>
                    <th>Date</th>
                    <th>Giving Area</th>
                    <th>Check/Trans #</th>
                    <th style="text-align: right;">Amount</th>
                </tr>
            </thead>
            {% sql %}
                SELECT 
                    t.[TransactionDateTime],
                    a.[PublicName],
                    t.[TransactionCode],
                    d.[Amount]
                FROM
                    [FinancialTransactionDetail] d
                    INNER JOIN [FinancialTransaction] t ON t.[Id] = d.[TransactionId]
                    INNER JOIN [PersonAlias] pa ON pa.[Id] = t.[AuthorizedPersonAliasId]
                    INNER JOIN [Person] p ON p.[Id] = pa.[PersonId]
                    INNER JOIN [FinancialAccount] a ON a.[Id] = d.[AccountId]
                WHERE
                    p.[GivingId] = '{{ CurrentPerson.GivingId }}'
                    AND DATEPART( yyyy, t.[TransactionDateTime]) = {{ selectedYear }}
            {% endsql %}
            
            
            {% for transactionDetail in results %}
                {{ transaction.Id }}
                <tr>
                    <td>{{ transactionDetail.TransactionDateTime | Date:'M/d/yyy' }}</td>
                    <td>{{ transactionDetail.PublicName }}</td>
                    <td>{{ transactionDetail.TransactionCode }}</td>
                    <td style="text-align: right;">{{ 'Global' | Attribute:'CurrencySymbol' }}{{ transactionDetail.Amount }}</td>
                </tr>
            {% endfor %}
        
        </table>
    </body>
</html>