Tutorial: Plantillas en PDFDocument

La característica de Plantilla en PDFDocument no es una característica nueva, pero ha recibido una importante mejora en la nueva release Xojo 2021r3. ¿Qué son las plantillas de PDFDocument o por qué querrías usarlas? Continúa leyendo para conocer los detalles.

Existen algunos escenarios en los que probablemente querrás utilizar las plantillas. Veamos algunos de ellos.

Como almacenamiento de los PDF

Bien, de acuerdo, puedes optar por archivar simplemente el PDF creado con la instancia de PDFDocument, ya sea como archivo o como un Blob en una base de datos; pero probablemente ahorrarás una buena cantidad de bytes si decides guardar la representación JSON del documento PDF obtenida con el método PDFDocument.Template.

Imaginemos que quieres guardar estos documentos, bueno, como simples “plantillas” para el propósito de tus aplicaciones y/o soluciones. La principal diferencia es que si las guardas como archivos PDF, entonces no podrás añadir posteriormente nuevos objetos, texto o cualquier elemento soportado por PDFDocument sobre ellos… dado que PDFDocument no puede parsear o recrear los objetos requeridos a partir de los flujos de datos de un archivo PDF.

Por el contrario, si guardas estas “plantillas” a un archivo o base de datos usando el método template;, entonces posteriormente podrás recrear una nueva instancia PDFDocument a partir de dichos datos. Todo lo que tendrás que hacer será pasar dichos datos JSON en el método Constructor de PDFDocument… ¡y listo! Esto significa que podrás continuar añadiendo nuevos elementos sobre dicha nueva instancia de PDFDocument: texto, formas, imágenes, formularios, nuevas páginas… Es decir, cualquiera de los elementos soportados por PDFDocument.template

Porque no quieres dibujar todo de nuevo

Una nueva instancia creada a partir de los datos obtenidos con el método Template implica que no hay necesidad de volver a “dibujar” de nuevo el PDF desde código Xojo. El Constructor de PDFDocument se hará cargo de todos los pasos necesarios para recrear los objetos requeridos a partir de los datos recibidos.

Es probable que pienses, “Bueno, mi aplicación ya incluye el código necesario para dibujar esos mismos documentos PDF” Y eso será cierto para algunos escenarios, pero no en todos ellos.

Piensa por ejemplo en una solución cuya aplicación principal se encargue de crear desde código estos documentos PDF que se utilizarán como base o “plantillas”, guardándolos posteriormente a una base de datos.

Luego, las aplicaciones cliente sólo tendrán que obtener cualquiera de estas “plantillas” PDF que precisen a partir de la base de datos, crear una nueva instancia PDF a partir de dichos datos, y añadir todo el contenido nuevo que precisen… sin tener que volver a duplicar el código que fue necesario para crear el documento PDF base en primer lugar.

Porque quieres ofrecer un Editor PDF visual a tus usuarios

Puede que estés pensando en ofrecer a los usuarios de tus aplicaciones un editor visual, de modo que puedan crear documentos PDF simplemente arrastrando y soltando controles aquí y allá desde un panel… tal y como haces, por ejemplo, cuando utilizas el Editor de Diseño del IDE de Xojo.

Si este es el caso, entonces realmente merecerá la pena ofrecer a tus usuarios una opción para que puedan guardar el documento PDF en su estado actual; de modo que puedan recuperarlo posteriormente para continuar editándolo, tal y como cabría esperar de cualquier tipo de editor. En dicho caso, y gracias al método PDFDocument.Template, ¡esto será realmente fácil! Sólo has de invocar dicho método sobre la instancia PDF y guardar los datos JSON obtenidos en el formato de archivo o motor de base de datos de tu elección.

Tus usuarios podrás ejecutar tu aplicación unas horas o días después, recuperar cualquier de los documentos PDF previamente guardados y continuar trabajando en ellos en el mismo punto en el que los dejaron.

Ejemplo rápido sobre el uso de PDFDocument.Template

Pongamos dicha característica en práctica con un ejemplo realmente sencillo. No será el más útil que puedas utilizar en una app del mundo real, pero servirá para ilustrar y comprender mejor como funciona.

Por tanto, empecemos con un fragmento de código encargado de crear un documento PDF realmente simple: algo de texto y un círculo añadido a un documento de una página:

Var d As New PDFDocument

Var g As Graphics = d.Graphics

g.FontSize = 30
g.DrawText "Hello there!", 50, 100

Var x, y As Double

x = g.Width/2 - 100
y = g.Height/2 - 100

g.DrawingColor = Color.Red
g.Transparency = 50.0

g.FillOval(x,y,200,200)

Var f As FolderItem = SpecialFolder.Desktop.Child("SamplePDF.pdf")
d.Save(f)
f.Open

Y este es el resultado del documento PDF (no es impresionante, pero funciona para los propósitos del ejemplo):

Añadamos ahora la línea de código para obtener los datos de “plantilla” a partir de dicha instancia de documento:

Var template As JSONItem = d.Template

Si examinásemos los datos JSON obtenidos, estos serían los siguientes:

{"General":{"Author":"","Creator":"Xojo","Keywords":"","Subject":"","Title":""},"Document":{"Compression":true,"EmbeddedFonts":false,"Landscape":false,"Width":612.0,"Height":792.0},"Actions":{"0":{"FontSize":"30.00"},"1":{"DrawText":"Hello there!,_ENDTEXT_,50.00,100.00,.00,False"},"2":{"Color":"&h00FF0000"},"3":{"Transparency":".50"},"4":{"FillOval":"206.00,296.00,200.00,200.00"}},"Images":{}}

Es decir, estos serían un total de 396 bytes en el caso de que guardásemos dichos datos como un archivo de texto. En comparación, nuestro archivo PDF de ejemplo tendría en este momento un tamaño de 1.380 bytes.

Vamos a crear ahora una nueva instancia de PDFDocument a partir de los datos de plantilla. Todo lo que necesitamos hacer es añadir estas líneas de código:

Var d2 As New PDFDocument(template)

Y este es el aspecto que tendría si decidimos guardarlo y abrirlo con un visor PDF:

Var f2 as FolderItem = SpecialFolder.Desktop.Child("SamplePDFFromTemplate.pdf")
d2.save(f2)
f2.Open

No es de sorprender, ¡obtenemos los mismos contenidos del PDF original! Después de todo, lo hemos creado a partir de… bueno… una plantilla.

El principal punto en este caso es que podemos continuar trabajando con la instancia d2, para añadir nuevos contenidos al PDF si así lo deseamos. Por tanto, cambiemos ligeramente el segundo fragmento de código:

Var template As JSONItem = d.Template

Var d2 As New PDFDocument(template)
Var g2 As Graphics = d2.Graphics
g2.DrawText "Hi From The Template!", 50, 160

En este caso ocurren un par de cosas interesantes. La primera es que no ha sido necesario definir el tamaño de la fuente, dado que utilizará el último valor de FontSize definido en el documento original a partir del cual se han obtenido los datos de Plantilla. Esto es lo mismo que ocurre con el color utilizado a la hora de añadir más texto en la nueva instancia de PDFDocument: utiliza el último color definido para la propiedad DrawingColor en el documento original.

Por tanto, a partir de este punto… ¡podemos añadir cualquier cosa que necesitemos en nuestro nuevo PDFDocument creado a partir de la plantilla! Incluso puedes pensar en el primer fragmento de código como el disponible sólo en la aplicación “principal” (la utilizada para crear el documento PDF original además de para obtener los datos de plantilla), mientras que el segundo fragmento de código sería el código ejecutado por tus apps “clientes” (la encargada de crear una nueva instancia PDFDocument a partir de los datos de plantilla).