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"?>

	<!—content related code goes here -->


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.

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!


  • 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
    After years of investments and acquisitions, CloudBlue was created with the goal of building the world's only hyperscale digital platform with an increasingly infinite ecosystem and proven go-to-market services. The result? An unmatched platform that helps customers streamline cloud operations, save time and money, and revolutionize their businesses overnight. Today, the platform operates in more than 45 countries and powers more than 200 of the world's largest cloud marketplaces, managing mo...
    BMC has unmatched experience in IT management, supporting 92 of the Forbes Global 100, and earning recognition as an ITSM Gartner Magic Quadrant Leader for five years running. Our solutions offer speed, agility, and efficiency to tackle business challenges in the areas of service management, automation, operations, and the mainframe.
    The platform combines the strengths of Singtel's extensive, intelligent network capabilities with Microsoft's cloud expertise to create a unique solution that sets new standards for IoT applications," said Mr Diomedes Kastanis, Head of IoT at Singtel. "Our solution provides speed, transparency and flexibility, paving the way for a more pervasive use of IoT to accelerate enterprises' digitalisation efforts. AI-powered intelligent connectivity over Microsoft Azure will be the fastest connected pat...
    At CloudEXPO Silicon Valley, June 24-26, 2019, Digital Transformation (DX) is a major focus with expanded DevOpsSUMMIT and FinTechEXPO programs within the DXWorldEXPO agenda. Successful transformation requires a laser focus on being data-driven and on using all the tools available that enable transformation if they plan to survive over the long term. A total of 88% of Fortune 500 companies from a generation ago are now out of business. Only 12% still survive. Similar percentages are found throug...
    Apptio fuels digital business transformation. Technology leaders use Apptio's machine learning to analyze and plan their technology spend so they can invest in products that increase the speed of business and deliver innovation. With Apptio, they translate raw costs, utilization, and billing data into business-centric views that help their organization optimize spending, plan strategically, and drive digital strategy that funds growth of the business. Technology leaders can gather instant recomm...
    At CloudEXPO Silicon Valley, June 24-26, 2019, Digital Transformation (DX) is a major focus with expanded DevOpsSUMMIT and FinTechEXPO programs within the DXWorldEXPO agenda. Successful transformation requires a laser focus on being data-driven and on using all the tools available that enable transformation if they plan to survive over the long term. A total of 88% of Fortune 500 companies from a generation ago are now out of business. Only 12% still survive. Similar percentages are found throug...
    As you know, enterprise IT conversation over the past year have often centered upon the open-source Kubernetes container orchestration system. In fact, Kubernetes has emerged as the key technology -- and even primary platform -- of cloud migrations for a wide variety of organizations. Kubernetes is critical to forward-looking enterprises that continue to push their IT infrastructures toward maximum functionality, scalability, and flexibility. As they do so, IT professionals are also embr...
    CloudEXPO has been the M&A capital for Cloud companies for more than a decade with memorable acquisition news stories which came out of CloudEXPO expo floor. DevOpsSUMMIT New York faculty member Greg Bledsoe shared his views on IBM's Red Hat acquisition live from NASDAQ floor. Acquisition news was announced during CloudEXPO New York which took place November 12-13, 2019 in New York City.
    In an age of borderless networks, security for the cloud and security for the corporate network can no longer be separated. Security teams are now presented with the challenge of monitoring and controlling access to these cloud environments, at the same time that developers quickly spin up new cloud instances and executives push forwards new initiatives. The vulnerabilities created by migration to the cloud, such as misconfigurations and compromised credentials, require that security teams t...
    The graph represents a network of 1,329 Twitter users whose recent tweets contained "#DevOps", or who were replied to or mentioned in those tweets, taken from a data set limited to a maximum of 18,000 tweets. The network was obtained from Twitter on Thursday, 10 January 2019 at 23:50 UTC. The tweets in the network were tweeted over the 7-hour, 6-minute period from Thursday, 10 January 2019 at 16:29 UTC to Thursday, 10 January 2019 at 23:36 UTC. Additional tweets that were mentioned in this...