arrow-left

Only this pageAll pages
gitbookPowered by GitBook
1 of 9

Ortus PDF Extension

Loading...

Intro

Loading...

Loading...

Loading...

Essentials

Loading...

Loading...

Loading...

Release History

A collection of all the major releases of this extension

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.

hashtag
Version 2.x

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

hashtag
Version 1.x

The birth of this Extension

Debugging

Issues? We all have them, learn how to cope with them

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.

Introduction

The Ortus PDF Extension is a Lucee Extension that will bring enhanced PDF tags and features to any Lucee CFML engine like cfpdfform, cfpdfformparam tags and much more.

hashtag
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.

hashtag
Requirements

  • Lucee 5.1.0 and above

hashtag
Commercial Product

This Lucee extension is a commercial product by Ortus Solutions. You will need to purchase a license:

hashtag
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:

hashtag
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:

  • Bug Tracker:

What's New With 2.0

Version 2 is a major rewrite to support Lucee 5

hashtag
Release Notes

hashtag
Bug

ORTUSPDF-38arrow-up-right Automated docs publishing not replacing the right token

hashtag
New Feature

ORTUSPDF-35arrow-up-right Upgrade to lucee 5 support

ORTUSPDF-36arrow-up-right Update docs to support lucee5

ORTUSPDF-37arrow-up-right Ability to read embedded sub-forms for elements

hashtag
Improvement

ORTUSPDF-34arrow-up-right Improvements to the extension activation process

  • 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!!

  • https://www.ortussolutions.com/products/ortuspdf#buyarrow-up-right
    https://www.ortussolutions.com/services/supportarrow-up-right
    https://ortussolutions.atlassian.net/browse/ORTUSPDFarrow-up-right

    About This Book

    The source code for this book is hosted on GitHub:

    https://github.com/ortus-docs/ortuspdfarrow-up-right

    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 - ​

    hashtag
    External Trademarks & Copyrights

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

    hashtag
    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.

    hashtag
    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.

    hashtag
    Charitable Proceeds

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

    hashtag
    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.

    https://www.ortussolutions.com/products/commandboxarrow-up-right
    https://www.harvesting.org/arrow-up-right

    Installation

    Getting started with the Ortus PDF Extension

    hashtag
    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.

    hashtag
    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.

    triangle-exclamation

    We recommend a complete server install so changes can take effect.

    hashtag
    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

    Just drop the 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

    hashtag
    Activating the Extension

    circle-exclamation

    If you do not see the menu, please completely restart your Lucee Server.

    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.

    circle-exclamation

    Development servers are FREE of charge, and each license includes up to 4 activations. Production licenses are on a per Lucee instance and are allowed 1 activation. If you have any activation issues, please contact us at . Also, make sure you have a valid internet connection to activate your product.

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

    hashtag
    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.

    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.

    hashtag
    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.

    hashtag
    Properties File License Configuration

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

    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.

    ortuspdf-2.0.0.lexarrow-up-right
    [email protected]envelope
    https://downloads.ortussolutions.com/#/ortussolutions/lucee-extensions/ortuspdf/2.0.0/arrow-up-right
    {lucee-server}/WEB-INF/lucee-server/deploy
    {lucee-server}/WEB-INF/lucee-server/context/logs/deploy.log
    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"] 

    Usage

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

    • cfpdfform

    • cfpdfformparam

    hashtag
    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:

    hashtag
    Basic Usage

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

    hashtag
    cfpdfform attributes

    hashtag
    cfpdfformparam attributes

    hashtag
    Examples

    Populating a PDF Form with sub params

    Populating a PDF Form with a struct

    Populating a PDF Form with a JSON object

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

    Reading a PDF Form

    Reading a PDF Form as JSON Data

    Reading a PDF Form as XML Data

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

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

    XML Data

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

    CFML Structure

  • XML string

  • XML file

  • FDF file

  • overwrite

    No

    populate, read

    No

    Specifies whether to overwrite the destination file (if action="populate") or the data file (if action="read"):

    overwriteData

    No

    populate

    No

    If enabled it will overwrite form field values, else it will only override them if the value is empty.

    result

    No

    read

    pdfdata

    ColdFusion structure that contains the form field values. If not used, the tag will create a variable called pdfdata for you in the caller scope.

    source

    Yes

    populate, read

    ---

    Pathname of the source PDF (absolute on-disk or in-memory path, or path relative to the context root) or byte array representing a PDF.

    flatten

    No

    populate

    true

    Will flatten the populated PDF so the form is sealed in the container PDF.

    structData

    No

    populate

    ---

    Instead of using nested cfpdfformparam tags, you can pass a struct of name-value pairs to populate a PDF form with.

    jsonData

    No

    populate,read

    ---

    Populate: Instead of using nested cfpdfformparam tags, you can pass a JSON object of name-value pairs to populate a PDF form with. Read : If a string, this will be the name of the variable in the caller's variables scope that will contain the form data as a JSON string.

    xmlData

    No

    read, populate

    ---

    Read : If a string, this will be the name of the variable in the caller's variables scope that will contain the Form data as an XML packet value. If this is a file path ending in .xml then the tag will export the XMl of the Form data to that file. Populate : The XML object, XML string or XML data filename to use when populating the PDF form instead of sub cfpdfformparam tags.

    ---

    ''Not implemented by Ortus PDF''

    Parameter

    Required

    Action

    Default

    Description

    action

    Yes

    ---

    read

    Action to perform: populate or read

    destination

    Yes

    populate

    ---

    Parameter

    Required

    Default

    Description

    name

    Yes

    ---

    The name of the PDF form entry

    value

    Yes

    ---

    The value of the PDF form entry

    index

    Pathname for the output file. You can specify an absolute pathname or a pathname relative to the context root. The file extension must be PDF. Do not specify the destination when you embed a form in a PDF document.

    ---

    <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>
    <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" />
    <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>
    <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>
    <cfpdfform 
        action="populate" 
        source="#datapath#/report.pdf" 
        overwrite="true"
        overwriteData="true"
        xmlData="c:\temp\data.xml"
        flatten="true">
    </cfpdfform>
    <cfpdfform 
        action="read"
        source="#dataPath#/report.pdf"
        result="formData">
    
    <cfdump var="#formData#">
    <cfpdfform 
        action="read"
        source="#dataPath#/report.pdf"
        jsonData="formData">
    
    <cfdump var="#isJSON( formData )#">
    <cfdump var="#formData#">
    <cfpdfform 
        action="read"
        source="#dataPath#/report.pdf"
        xmlData="formData">
    
    <cfdump var="#isXML( formData )#">
    <cfdump var="#formData#">
    <cfpdfform 
        action="read"
        source="#dataPath#/report.pdf"
        xmlData="c:\temp\export.xml">
    <cfpdfform 
        action="read"
        source="#dataPath#/report.pdf"
        fdfData="c:\temp\export.fdf">
    <?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>
    Harvesting in Spanish - Evangelism With A Heartharvesting.orgchevron-right
    www.harvesting.org
    Logo