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
    Every organization is facing their own Digital Transformation as they attempt to stay ahead of the competition, or worse, just keep up. Each new opportunity, whether embracing machine learning, IoT, or a cloud migration, seems to bring new development, deployment, and management models. The results are more diverse and federated computing models than any time in our history.
    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...
    Japan DX Pavilion at @CloudEXPO Silicon Valley
    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...
    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...
    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...
    Where many organizations get into trouble, however, is that they try to have a broad and deep knowledge in each of these areas. This is a huge blow to an organization's productivity. By automating or outsourcing some of these pieces, such as databases, infrastructure, and networks, your team can instead focus on development, testing, and deployment. Further, organizations that focus their attention on these areas can eventually move to a test-driven development structure that condenses several l...
    The term "digital transformation" (DX) is being used by everyone for just about any company initiative that involves technology, the web, ecommerce, software, or even customer experience. While the term has certainly turned into a buzzword with a lot of hype, the transition to a more connected, digital world is real and comes with real challenges. In his opening keynote, Four Essentials To Become DX Hero Status Now, Jonathan Hoppe, Co-Founder and CTO of Total Uptime Technologies, shared that ...
    Over the course of two days, in addition to insightful conversations and presentations delving into the industry's current pressing challenges, there was considerable buzz about digital transformation and how it is enabling global enterprises to accelerate business growth. Blockchain has been a term that people hear but don't quite understand. The most common myths about blockchain include the assumption that it is private, or that there is only one blockchain, and the idea that blockchain is...
    Never mind that we might not know what the future holds for cryptocurrencies and how much values will fluctuate or even how the process of mining a coin could cost as much as the value of the coin itself - cryptocurrency mining is a hot industry and shows no signs of slowing down. However, energy consumption to mine cryptocurrency is one of the biggest issues facing this industry. Burning huge amounts of electricity isn't incidental to cryptocurrency, it's basically embedded in the core of "mini...