Welcome!

You will be redirected in 30 seconds or close now.

ColdFusion Authors: Yakov Fain, Jeremy Geelan, Maureen O'Gara, Nancy Y. Nee, Tad Anderson

Related Topics: ColdFusion

ColdFusion: Article

Creating Free PDFs from Your CF Application

Utilize FOP from Apache

I'm sure most of you have been in a situation where either your employer or customer doesn't like the way content from a Web browser looks when printed. There are many ways to provide printable content, but one of the most popular formats of printable material is PDF format. There are many solutions to creating PDF documents from your ColdFusion application, but they all cost money right?

Some PDF solutions are not cheap at all and maybe cost isn't the only issue. Maybe you want to do it yourself without using a CFX tag. What if I told you there was a way to create PDFs from CF for free without using a CFX tag? Would you be interested? If so, then read on...

In this article I will demonstrate how to create PDFs from your ColdFusion application for free. I will be utilizing FOP (Formatting Objects Processor) from Apache, which is of course free. This will integrate well with ColdFusion because it can be invoked as a Java object.

What Is FOP?
FOP is part of Apache's XML project. The latest version of FOP (0.20.5) was released on July 18, 2003. It is a partial implementation of the XSL-FO Version 1.0 W3C Recommendation. Support for each of the standard's objects and properties are detailed at http://xml.apache.org/fop/compliance.html. FOP is the world's first print formatter driven by XSL formatting objects (XSL-FO) and the world's first output independent formatter. It is a Java application that reads a formatting object tree and renders the resulting pages to a specified output. PDF is the primary output target, but many others are also supported, listed at http://xml.apache.org/fop/output.html. The PDF version supported is 1.3, which is currently the most popular version for Acrobat Reader (4.0); PDF versions are forwards/backwards compatible. For more information about FOP visit http://xml.apache.org/fop.

The Quick Shakedown
Just so you know what you're getting into before reading on, here's a quick shakedown of what I will explain in detail through the rest of this article. The main points in this process are:

  • FOP is easily installed on a CF server.
  • CF generates an XML file.
  • XML file is transformed by using XSL-FO.
  • CF invokes an FOP component to dynamically generate a PDF.
  • FOP component reads transformed XML.
  • FOP component converts transformed XML into a PDF format by using Java objects.
  • Browser returns a PDF document.
Installing FOP
Installing FOP is very easy and works like a charm as long as you have all the necessary components in place and of course, pay attention. Here are the detailed steps:

1.  In order to use the provided code it is required that you have ColdFusion MX installed.

2.  Since FOP is a Java application, you'll need an installed Java 2 SDK, version 1.2 or later. The latest Sun J2SE downloads can be found at http://java.sun.com/j2se/downloads/index.html. At the top you will see links to the latest J2SEs. Currently the latest stable J2SE is 1.4.2. Under the heading "Download J2SE v 1.4.2_04" find the corresponding download for your OS and then click "Download". If you need further instructions go to http://java.sun.com/j2se/1.4.2/install.html.

3.  Next on the list is to download the latest binary build of FOP (0.20.5) from Apache. Go to http://apache.secsup.org/dist/xml/fop/ and click on fop-0.20.5-bin.tar.gz to download. Download the file and extract it to the directory of your choice. After the file has been extracted you need to copy the following three .jar files to your CFMX jre\lib directory; a common location is C:\CFusionMX\runtime\jre\lib.

  • <fop-extracted-dir>\build\fop.jar
  • <fop-extracted-dir>\lib\avalon-framework-cvs-20020806.jar
  • <fop-extracted-dir>\lib\batik.jar
4.  After copying those files to your CFMX jre\lib directory you will then be required to add the fop.jar file to the classpath in your CF Admin. Using the common location I listed above you would add C:\CFusionMX\runtime\jre\lib\fop.jar to your classpath as shown in Figure 1. If your classpath is not empty, then separate the entries by a comma. You will then be required to restart your ColdFusion MX Application Server. If you do not know how to do this read step 5, otherwise you are now ready to use FOP! Step 6 is only important for using the code provided with this article.

5.  To restart the ColdFusion MX Application Server right-click on "My Computer" and choose "Manage". Then expand "Services and Applications", click on "Services" and you should see the CFMX Application Service listed. If so, then right-click and choose "Restart". If this doesn't work for you then you will need to visit your OS help.

6.  This step is only important for using the code provided with this article. Create a directory under your wwwroot to store the provided code. I will demonstrate the creation of all the necessary files except for the FOP component. I downloaded FOP.cfc from Nate Weiss at http://nateweiss.com/ and I have included the code in Listing 7.

That wasn't so bad now was it?

The Example
I will now continue by introducing the example that I will be using through the rest of the article. I have chosen an example that will help demonstrate the capabilities of FOP as well as be simple enough to not take over the article. I have created a very simple two-table database that is by no means normalized, which I do not recommend, but that will work for what I am using it for. I created a SQL database named "FOPExample" and created it as a data source in my CF Admin, named "FOPExample" as shown in Figure 2. I created one table to contain the 50 United States and another table to contain customers with their corresponding city and state. I have provided the SQL scripts to create these tables (see Listing 1).

I will start with a basic form that contains a multi-select list of the 50 states (see Listing 2). This basic form will submit to generatexml.cfm (see Listing 3), a file I have created that will read the example database to fetch a list of the customers located in the chosen state(s). Then I will output these customers into an XML file. The PDF could be automatically created next, but to show a step-by-step process I provide a link to generate the PDF. After clicking the link, the FOP component will be invoked to create the PDF file. To show the capabilities of XSL-FO I have designed this to group by state on the PDF output. Sounds pretty cool, right? If I haven't bored you to death yet, then please continue as I will now explain the step-by-step process in more detail.

Generating the XML
Now the fun begins as I will demonstrate the dynamic creation of the XML file to be transformed into PDF content as shown in Listing 3. In this file I query the FOPExample database to get the customers and their info for those that are in the states chosen from the form. In this case I chose California, Colorado, and Minnesota. To easily create a properly formatted XML string I use the <cfxml> tag by wrapping it around the XML content that I will generate. I have used only XML in this output because all of the display formatting will come from the XSL file in the XML transformation.

The first XML tag I will create in this file is the very top level output, in this case <project>. If you are familiar with the way XML tags work you will notice I have named the project "FOPExample". I was a little lazy and "hardcoded" this value, but it could be dynamic if you had multiple projects. I will display the project line as a header in the PDF file.

To generate the rest of the XML content I use a simple <cfoutput> and take advantage of the group attribute in order to group the XML by state. After outputting the state I then move on to customers by using <customers> as a wrapper with <person> inside. Wrapped in the <person> tag I output the names of each person and all of the other attributes of that person are added by adding a corresponding attribute to the <person> tag. Take note of these attribute names and tag names because I will refer to them when creating the XSL file.

After generating my XML string I input it into the <cffile> tag to save it as an XML file on the server. The FOP process could be done without actually saving the XML file, but I have done so to easily show the step-by-step process. Saving the XML file is not recommended if you are generating sensitive data. If you are not generating sensitive data, this could be an advantage if you are generating a very large "one time" report because you won't have to hit the database again as you can just render the XML file. After generating the XML file I suggest opening it in your favorite text editor to see how it is formatted (see Listing 4) and to make sure it is formatted the way you expected. Next I use a simple HTML link to fire off the PDF generation process. Before actually firing off the process we are still missing one very important piece - the XSL file.

Creating the XSL file
FOP generates a PDF file by reading transformed XML code. In order to provide this we must now create an XSL-FO file. Open your favorite editor that hopefully supports XSL code. If you do not have one don't worry, it's just easier with one. I actually prefer to use TextPad, which you can try for free and which is very cheap to buy. TextPad has syntax file plugins for quite a few languages and runs very light on the processor. You can download TextPad at www.textpad.com and you can get the syntax files at www.textpad.com/add-ons/files/utilities/synfile.zip.

Now we are really cruising as we will dip into FOPExample.xsl. In order to have a correctly formatted XSL-FO document it must contain all of the following (except for my comment of where the content goes).


<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet
	xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
	xmlns:fo="http://www.w3.org/1999/XSL/Format"
	version="1.0">

	<!—content related code goes here -->

</xsl:stylesheet>

Now for the content. I will start by giving a few simple comparisons that really helped me understand the basic XSLT elements (see Figure 3).

I will start the content with <xsl:template match="/project"> as you may notice the value to the match attribute equals the name of the top level XML tag I used when generating the XML output. Next comes another required tag for XSL-FO followed by the page layout properties of the template, commented as "defines page layout" in Listing 5.

I'm not going to actually go into detail about each of these attributes, but you can see that it is very customizable. The next tag used is for the page numbering that you display in the PDF: <fo:page-sequence master-reference="only" initial-page-number="1">. After this tag you will see a static content <fo:block> commented as "Header" in Listing 5.

If you look at the numerous <fo:block> tags, you may notice these are at each level of content and are used for formatting. Wrapped inside the beginning and end tags can be actual text, or if you want to output a variable like I have done in this example you would use: <xsl:value-of select="@variable"/>. Variable is actually the name of the attribute to the XML tag in the generated XML output. You will also see the tag: <xsl:for-each select="usstate">. This is used similarly to the way you would use <cfloop> while looping over each state, and inside that loop you are going to display the related customers.

So is the XSL-FO effort making sense now? You can see the entire FOPExample.xsl in Listing 5. I commented the important pieces to help you understand where everything is. If you need more specific help with the XSL file see http://zvon.org/xxl/xslfoReference/Output/index.html.

Transforming the XML
Now that I have my XML and XSL files I can transform my XML to prepare it for FOP. This process is so much easier than it sounds thanks to the XML functions in ColdFusion. To do this I will use the XMLTransform() function as shown in Listing 6. I will use the <cffile> tag to read the contents of both my XML and XSL files. I will then pass the output from both of these files into the XMLTransform function. The XMLTransform function asks for my XML string, then my XSL string. I will set the transformed outout to a variable. Now you have a transformed XML string to pass into the FOP component.

Invoking FOP
Now that the hard part is done we will invoke the FOP component that I downloaded from Nate Weiss. This is done by using the <cfinvoke> tag. I will invoke the FOP component and I will be using the ConvertStringToPDF method. In order to use this method it is required to pass in values to two arguments. FoString, which takes the transformed XML string and pdfFile, which will be used to give the name and location for the PDF file to be created. The other method available in this component is ConvertFileToPDF, which works the same way but instead of passing the transformed XML string into it, you will give the name and location of a file that contains the transformed XML.

If you look at the code for the FOP component in Listing 7 you may notice another method that is actually used internally to generate the PDF. This method uses proper locking procedures since FOP is not thread safe. Because it is not thread safe a new instance of the Apache driver must be created each time it is used. Thanks to an already provided component this process was simple too. We are just moving right along now. Next you will actually see the results that you have been waiting for.

Displaying the PDF
In order to display the PDF file in the browser I will use the <cfcontent> tag. This is once again a very simple process as I pass into it the name and full path to the generated PDF file. The other attribute I must use for this tag is the type attribute, which I will set to "application/pdf" for the PDF file format. Now that the code is all explained and created it's time to click that link that we added to the bottom of generatexml.cfm in Listing 3. A new window should pop up with your dynamically generated content. The content should look like it does in Figure 4. If yours didn't work, then hopefully there was just a simple step missed. Remember this process can be very simple, but it is picky and it won't work at all if something is missing.

Conclusion
Well, now that you know FOP is not scary to use, you will be on your way to creating PDFs for free. I only touched on the essentials of FOP in this article. There are many other capabilities such as PDF encryption, SVG support, and including a linked Table of Contents. The example that I demonstrated was a very simple task; there are many other possibilities this could be used for. Look forward to Part 2 of this article as I will explore some of the other FOP capabilities. As a fellow developer, I enjoy informing other developers that there are many possibilities when it comes to finding solutions to your projects. I know it seems like this is difficult and takes a long time to learn, but once you try it for yourself you will realize that it's actually fairly easy. Good luck!

Resources

  • The FOP project http://xml.apache.org/fop/
  • Pawson, Dave: XSL-FO Making XML Look Good in Print (O'REILLY) ISBN: 0-596-00355-2
  • An XSL-FO reference http://zvon.org/xxl/xslfoReference/Output/index.html
  • More Stories By Nate Nelson

    Nate Nelson is a senior software developer for I*LEVEL, Inc., a software startup in Englewood, Colorado, where he leads development efforts of a commercial software product. He is a member of the Denver CFUG administration.

    Comments (20)

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


    IoT & Smart Cities Stories
    In his general session at 19th Cloud Expo, Manish Dixit, VP of Product and Engineering at Dice, discussed how Dice leverages data insights and tools to help both tech professionals and recruiters better understand how skills relate to each other and which skills are in high demand using interactive visualizations and salary indicator tools to maximize earning potential. Manish Dixit is VP of Product and Engineering at Dice. As the leader of the Product, Engineering and Data Sciences team at D...
    Bill Schmarzo, Tech Chair of "Big Data | Analytics" of upcoming CloudEXPO | DXWorldEXPO New York (November 12-13, 2018, New York City) today announced the outline and schedule of the track. "The track has been designed in experience/degree order," said Schmarzo. "So, that folks who attend the entire track can leave the conference with some of the skills necessary to get their work done when they get back to their offices. It actually ties back to some work that I'm doing at the University of San...
    When talking IoT we often focus on the devices, the sensors, the hardware itself. The new smart appliances, the new smart or self-driving cars (which are amalgamations of many ‘things'). When we are looking at the world of IoT, we should take a step back, look at the big picture. What value are these devices providing. IoT is not about the devices, its about the data consumed and generated. The devices are tools, mechanisms, conduits. This paper discusses the considerations when dealing with the...
    Bill Schmarzo, author of "Big Data: Understanding How Data Powers Big Business" and "Big Data MBA: Driving Business Strategies with Data Science," is responsible for setting the strategy and defining the Big Data service offerings and capabilities for EMC Global Services Big Data Practice. As the CTO for the Big Data Practice, he is responsible for working with organizations to help them identify where and how to start their big data journeys. He's written several white papers, is an avid blogge...
    Dynatrace is an application performance management software company with products for the information technology departments and digital business owners of medium and large businesses. Building the Future of Monitoring with Artificial Intelligence. Today we can collect lots and lots of performance data. We build beautiful dashboards and even have fancy query languages to access and transform the data. Still performance data is a secret language only a couple of people understand. The more busine...
    Enterprises have taken advantage of IoT to achieve important revenue and cost advantages. What is less apparent is how incumbent enterprises operating at scale have, following success with IoT, built analytic, operations management and software development capabilities - ranging from autonomous vehicles to manageable robotics installations. They have embraced these capabilities as if they were Silicon Valley startups.
    Chris Matthieu is the President & CEO of Computes, inc. He brings 30 years of experience in development and launches of disruptive technologies to create new market opportunities as well as enhance enterprise product portfolios with emerging technologies. His most recent venture was Octoblu, a cross-protocol Internet of Things (IoT) mesh network platform, acquired by Citrix. Prior to co-founding Octoblu, Chris was founder of Nodester, an open-source Node.JS PaaS which was acquired by AppFog and ...
    The deluge of IoT sensor data collected from connected devices and the powerful AI required to make that data actionable are giving rise to a hybrid ecosystem in which cloud, on-prem and edge processes become interweaved. Attendees will learn how emerging composable infrastructure solutions deliver the adaptive architecture needed to manage this new data reality. Machine learning algorithms can better anticipate data storms and automate resources to support surges, including fully scalable GPU-c...
    Cloud-enabled transformation has evolved from cost saving measure to business innovation strategy -- one that combines the cloud with cognitive capabilities to drive market disruption. Learn how you can achieve the insight and agility you need to gain a competitive advantage. Industry-acclaimed CTO and cloud expert, Shankar Kalyana presents. Only the most exceptional IBMers are appointed with the rare distinction of IBM Fellow, the highest technical honor in the company. Shankar has also receive...
    The standardization of container runtimes and images has sparked the creation of an almost overwhelming number of new open source projects that build on and otherwise work with these specifications. Of course, there's Kubernetes, which orchestrates and manages collections of containers. It was one of the first and best-known examples of projects that make containers truly useful for production use. However, more recently, the container ecosystem has truly exploded. A service mesh like Istio addr...