Version 2 is a major rewrite to support Lucee 5

Release Notes

Bug

ORTUSPDF-38 Automated docs publishing not replacing the right token

New Feature

ORTUSPDF-35 Upgrade to lucee 5 support

ORTUSPDF-36 Update docs to support lucee5

ORTUSPDF-37 Ability to read embedded sub-forms for elements

Improvement

ORTUSPDF-34 Improvements to the extension activation process

Ortus PDF Extension v2.x Docs

The Ortus PDF Lucee Extension adds the missing PDF capabilities you were longing for to any Lucee engine and enhances some PDF capabilities. The extension contains several new CFML built-in tags and functions to help you manipulate and work with PDF documents.

Requirements

• Lucee 5.1.0 and above

Commercial Product

This Lucee extension is a commercial product by Ortus Solutions. You will need to purchase a license: https://www.ortussolutions.com/products/ortuspdf#buy

Features In A Nutshell

• cfpdfform tag implementation compliant with Adobe ColdFusion

• cfpdfformparam tag implementation compliant with Adobe ColdFusion

• Ability to export PDF form data into:

  • Native CFML Structures

  • XML String

  • XML File

  • FDF File

  • JSON (Ortus Feature)

• Ability to pre-fill PDF form data from:

  • Native CFML Structures

  • XML String

  • XML File

  • XML Objects

  • JSON objects

• Allows the ability to flatten PDFs after populating them with data

• Manipulates existing forms created in Adobe® Acrobat® and Adobe® LiveCycle® Designer

• Ability to stream generated PDFs to browser

• Support for embedded forms (New since v2.1.0)

• Much More!!

Support

The Ortus PDF Extension is a commercial product by Ortus Solutions. If you have purchased a license, you are entitled to customer support. You can visit our support page to contact us or create an issue in our bug tracker.

• Support Page: https://www.ortussolutions.com/services/support

• Bug Tracker: https://ortussolutions.atlassian.net/browse/ORTUSPDF

In this section, you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions, use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

Version 2.x

Version 2 is a major extension rewrite to support Lucee 5, container deployments, and licensing updates.

Version 1.x

The birth of this Extension

The source code for this book is hosted on GitHub:

https://github.com/ortus-docs/ortuspdf

You can freely contribute to it and submit pull requests. Ortus Solutions, Corp copyright the contents of this book and cannot be altered or reproduced without the author's consent. All content is provided "As-Is" and can be freely distributed.

• The majority of code examples in this book are done in cfscript.

• The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL - https://www.ortussolutions.com/products/commandbox​

External Trademarks & Copyrights

Redis is a copyright and trademark of Redis Labs, Inc.

Notice of Liability

The information in this book is distributed “as is”, without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity concerning loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software, and resources described in it.

Contributing

We highly encourage contribution to this book and our open source software. The source code for this book can be found in our GitHub repository where you can submit pull requests.

Charitable Proceeds

10% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - https://www.harvesting.org/. So please donate and purchase the printed version of this book, every book sold can help a child for almost 2 months.

Shalom Children's Home

Shalom Children’s Home is one of the ministries that is dear to our hearts located in El Salvador. During the 12 year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children came on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.

Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education and life skills training in a Christian environment. The home is supported by a child sponsorship program.

We have personally supported Shalom for over 6 years now; it is a place of blessing for many children in El Salvador that either have no families or have been abandoned. This is good earth to seed and plant.

Lucee Setup

The extension is installed as a Lucee extension into any Lucee Server version 5.1.0 and above. The extension has to be installed at the server-level context.

All web contexts created under the same Lucee instance will have the extension tags deployed to them automatically for you.

Installing the Extension

Now click Extensions > Applications and wait for the list to load. There should be an item in the list called Ortus PDF. You can activate it as a trial or as a full version with a license key after you install it.

Click it and then click the install button to begin the installation process.

Manual/Docker Installation

Lucee also allows you to deploy the extension file (.lex) into a special folder. Lucee will detect the extension and automatically install it for you. The location is the following

{lucee-server}/WEB-INF/lucee-server/deploy

Just drop the ortuspdf-2.0.0.lex file in that folder, wait a few seconds, and it will automatically install. You can drop the file there before the server is started or during a started server.

If anything goes wrong during the installation, please verify the deploy logs in the following location

{lucee-server}/WEB-INF/lucee-server/context/logs/deploy.log

Activating the Extension

Production servers get only 1 activation, so make sure you choose the correct server type. Once you get all your information in the form, click on the activate button to finalize the installation. Choose the trial option if you don't have a license and just want to try out the extension. When the trial expires, the provider will stop working! The trial is not for production use.

The Ortus Lucee PDF Extension should now be installed on your server and ready to use.

Downloading The Extension

If you will be using an offline installation or a Docker-based installation, you can either follow the process above or download the extension and leverage a continuous integration server to build your images or server configurations. Please note that you will need a containerized server license to use this extension across multiple images.

https://downloads.ortussolutions.com/#/ortussolutions/lucee-extensions/ortuspdf/2.0.0/

From our artifact repository, download the appropriate lex file and drop it into your Lucee deploy folder: {lucee-server}/WEB-INF/lucee-server/deploy. Once the engine starts, it will deploy the extension for you automatically.

Automatic Activation

If you will be using Kubernetes, Docker Swarm or any other orchestrator, you will need to automate the activation process. There are two methods of providing your activation information to the extension:

1. Activation via a properties file in the extension filesystem

2. Activation via environment variables

Since you will likely want the server warmed up and ready to go, you may provide one of these two mechanisms in your build process. With environment variable-based activation, there is no need to hard-code the license information into the container build, though you may do so. Simply supply these environment keys at runtime or via a .env file.

Properties File License Configuration

To use the properties file method of license configuration, Create a license.properties file with the following content:

email=[The email address used to purchase your extension]
licenseKey=[The license key you were provided at registration]
activationCode=[The activation code for your extension and server type]
serverType=[ Activation type. Optional. Default to "Production"] 

And place it in the following location: {lucee-server}/WEB-INF/lucee-server/context/context/ortus/pdf/license.properties

Upon server startup, the file will be sourced in and the extension activated.

Here's a general list of troubleshooting steps if you're getting errors. The log files are VERY important since Lucee's error doesn't always contain the information you need. You must crack open your Lucee logs to get the actual error out.

• Look in the out and err logs for information. These are usually found in the servlet container's log directory. For instance, if you're using Tomcat, look in Tomcat's log directory. Messages are often logged there that never make it up to the CFML engine.

• Always scroll to the bottom of Java stack traces to look for a caused by section, which is the original error.

The Ortus PDF extension will give you the following available tags:

• cfpdfform

• cfpdfformparam

cfpdfform/cfpdfformparam

This tag allows you to manipulate existing PDF forms, usually edited in Adobe Acrobat or LiveCycle Designer. You will be able to do the following:

• Embed a form with pre-filled FORM data and deliver it via cfcontent or cfpdf or cfdocument tags

• Render out a pre-filled FORM to disk with overwrite and flattening capabilities.

• Extract values from a PDF form as:

  • CFML Structure

  • XML string

  • XML file

  • FDF file

Basic Usage

<cfpdfform
    action = "populate"
    source = "PDF file pathname|byte array"
    destination = "output file pathname"
    overwrite = "yes|no"
    overwriteData = "yes|no"
    xmlData = "XML object|XML string|XML data filename"
    structData = "CFML Struct">
    
    <cfpdfformparam name="" value="" index="" />

</cfpdfform>

<cfpdfform
    action = "read"
    source = "pathname|byte array"
    result = "structure containing form field values"
    overwrite = "yes|no"
    xmlData = "variable containing xml values or an XML file path"
    fdfData = "The absolute file path to export the data as FDF"> 
</cfpdfform>

The cfpdfform tag can have nested cfpdfformparam tags in order to populate forms inside PDF documents.

cfpdfform attributes

cfpdfformparam attributes

Examples

Populating a PDF Form with sub params

<cfpdfform 
    action="populate" 
    source="#datapath#/report.pdf" 
    destination="#workpath#/report-out.pdf" 
    overwrite="true"
    overwriteData="true"
    result="myresult"
    flatten="true">
    <cfpdfformparam name="full_name" value="Ortus Rocks" />
    <cfpdfformparam name="exam_date" value="#dateFormat( now(), "mmmm dd, yyyy")# #timeFormat( now(), "medium")#" />
    <cfpdfformparam name="strategy_overview" value="Drink a lot of water!" />
    <cfpdfformparam name="strategy_tips" value="Eat a lot of cheese!" />
</cfpdfform>

<!-- Deliver the file -->
<cfcontent file="#workpath#/report-out.pdf" type="application/pdf" reset="true" />

Populating a PDF Form with a struct

<cfset data = {
    "full_name" 		= "Ortus Rocks",
    "exam_date" 		= "#dateFormat( now(), "mmmm dd, yyyy")# #timeFormat( now(), "medium")#",
    "strategy_overview" = "Drink a lot of water!",
    "strategy_tips" 	= "Eat a lot of cheese!"
}>
<cfpdfform 
    action="populate" 
    source="#datapath#/report.pdf" 
    overwrite="true"
    overwriteData="true"
    structData=data
    flatten="true">
</cfpdfform>

Populating a PDF Form with a JSON object

<cfset jsonData = '{
    "full_name" 		: "Ortus Rocks",
    "exam_date" 		: "#dateFormat( now(), "mmmm dd, yyyy")# #timeFormat( now(), "medium")#",
    "strategy_overview" : "Drink a lot of water!",
    "strategy_tips" 	: "Eat a lot of cheese!"
}'>
<cfpdfform 
    action="populate" 
    source="#datapath#/report.pdf" 
    overwrite="true"
    overwriteData="true"
    jsonData="#jsonData#"
    flatten="true">
</cfpdfform>

Populating a PDF Form from and XML file and stream to browser

<cfpdfform 
    action="populate" 
    source="#datapath#/report.pdf" 
    overwrite="true"
    overwriteData="true"
    xmlData="c:\temp\data.xml"
    flatten="true">
</cfpdfform>

Reading a PDF Form

<cfpdfform 
    action="read"
    source="#dataPath#/report.pdf"
    result="formData">

<cfdump var="#formData#">

Reading a PDF Form as JSON Data

<cfpdfform 
    action="read"
    source="#dataPath#/report.pdf"
    jsonData="formData">

<cfdump var="#isJSON( formData )#">
<cfdump var="#formData#">

Reading a PDF Form as XML Data

<cfpdfform 
    action="read"
    source="#dataPath#/report.pdf"
    xmlData="formData">

<cfdump var="#isXML( formData )#">
<cfdump var="#formData#">

Reading a PDF Form as XML Data into an XML output file

<cfpdfform 
    action="read"
    source="#dataPath#/report.pdf"
    xmlData="c:\temp\export.xml">

Reading a PDF Form in FDF format and outputting to a file

<cfpdfform 
    action="read"
    source="#dataPath#/report.pdf"
    fdfData="c:\temp\export.fdf">

XML Data

If you will be populating forms or extracting forms, the format in XML will be the following:

<?xml version="1.0" encoding="UTF-8"?>
<fields
><exam_date
>October 31, 2013 10:00am</exam_date
><full_name
>Populated by XML</full_name
><keystrengths
>After training, the dimensions of Radical Innovation upon which 
you performed highest were RECEPTIVITY and SELF-INQUIRY.</keystrengths
></fields>