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) View Comments

    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.


    Most Recent Comments
    Joe Moore 12/23/04 02:50:47 PM EST

    I've tried to implement this on my test (single user comes with Studio) platform of CF MX (we run a production server, also). I've just upgraded my test server to 6.1 and installed Sun's JDK as you listed in the article.

    The example works fine. However, as soon as I start to modify it, whenever I make a mistake I get a java error and dump. Then, my server quits recognizing .cfm pages. Starting and stopping the CF server does not help. Starting and stopping Apache doesn't help. Only a cold boot allows my server to recognize .cfm pages again.

    Help!

    How do I start to debug this?

    Joe Moore
    South Dakota State University

    New Yorker 10/23/04 11:07:39 PM EDT

    Feel like the msg about CF is ready for integration with open source.

    Neil Giarratana 05/26/04 04:12:38 PM EDT

    This solution is fairly web server agnostic. It will work on both Apache and IIS (and pretty much anything ColdFusion will connect to...).

    bill foresman 05/26/04 02:34:15 PM EDT

    How about an IIS solution or does this work on Win 2K?

    charlie arehart 05/21/04 01:43:31 PM EDT

    Jeff, if you mean how they''re shown when all feedback is displayed (http://www.sys-con.com/story/feedback.cfm?storyid=44771), it''s clearly from oldest to newest. If you mean on the page of the article itself, it only shows the latest feedback item.

    jeff 05/20/04 11:17:10 PM EDT

    What''s with the sort order on this thread?

    Nate Nelson 05/20/04 12:29:24 PM EDT

    Thank you Neil and Charlie!

    Neil Giarratana 05/20/04 11:16:56 AM EDT

    Forgot to mention in my previous comment that I have a presentation that I''ve given at MXNorth, MXVegas, etc. on this topic. If anyone would find it of interest, you can download using the following url: http://www.lucidus.net/fop.zip

    Bob Campbell 05/20/04 06:11:45 AM EDT

    Neil,
    I tried, "copying the three jar files to C:\JRun4\servers\cfusion\cfusion-ear\cfusion-war\WEB-INF\lib\ and restart(ing) the web application..." as you suggested. Worked like a charm. ColdFusion restarted with no problem. I''ll finish the tutorial tonite when I get home and let you know how it turns out...
    Thanks,
    Bob

    charlie arehart 05/19/04 05:30:30 PM EDT

    Yep, it botched it. You can''t see the <CFSCRIPT> tags that I had around that code. Plus it mashed things onto one line. here it is again:

    <cfscript>
    getcustomers=querynew("customerfirstname,customerlastname,customercity,customerstatecode,usstatename");
    queryaddrow(getcustomers,1);
    querysetcell(getcustomers,"customerfirstname","charles");
    querysetcell(getcustomers,"customerlastname","arehart");
    querysetcell(getcustomers,"customercity","alpharetta");
    querysetcell(getcustomers,"customerstatecode","ga");
    querysetcell(getcustomers,"usstatename","georgia");
    </cfscript>

    charlie arehart 05/19/04 05:28:29 PM EDT

    Excellent job, Nate. I''ve been meaning to do such an article so I''m glad to instead point people to yours. I''d like to add a comment (some will see this coming): everything in this article applies to BlueDragon as well. Just copy the jars into the BlueDragon lib directory (on my machine, it''s C:\BlueDragon_Server_JX_61\lib, for instance), and just as Nate says to add the path to the fop.jar to the JVM classpath in the CF admin, you need to do the same in the BlueDragon admin, and restart. The example will work.

    Indeed, for someone wanting to test his example code without having to define a database and populate it, I just added the following to the top of generatexml.cfm in place of the CFQUERY:

    getcustomers=querynew("customerfirstname,customerlastname,customercity,customerstatecode,usstatename");
    queryaddrow(getcustomers,1);
    querysetcell(getcustomers,"customerfirstname","charles");
    querysetcell(getcustomers,"customerlastname","arehart");
    querysetcell(getcustomers,"customercity","alpharetta");
    querysetcell(getcustomers,"customerstatecode","ga");
    querysetcell(getcustomers,"usstatename","georgia");

    I hope the comment system here renders that correctly. If it doesn''t, I''ll come back and offer it cleaned up.

    And note that in using this I just called the generatexml.cfm file directly without using the basicform.cfm he offered. I just wanted to test the bare minimum capability. Hope that may help others.

    Neil Giarratana 05/19/04 04:52:51 PM EDT

    Yikes...part of my original message was dropped...here we go again: try copying the three jar files to C:\JRun4\servers\cfusion\cfusion-ear\cfusion-war\WEB-INF\lib\ and restart the web application. You should not need to add it to the classpath as anything in WEB-INF\lib should automatically be referenced...

    Neil Giarratana 05/19/04 04:50:32 PM EDT

    Bob: I would recommend copying the jar files mentioned in the article (batik, avalon and fop) to the /wwwroot/WEB-INF/lib directory. Restart the server and you should be good to go (without doing the JRun classpath adjustment).

    Scott Morrison 05/19/04 01:51:27 PM EDT

    How about a Server 2000 or 2003 installation and IIS 5?

    Nate Nelson 05/17/04 12:06:58 PM EDT

    Has anyone had a chance to use FOP with CFMX Enterprise?

    Jeff Jones 05/15/04 12:13:40 PM EDT

    Works great. Now how to I generate PDF on the fly from Word docs or HTML files?

    Bob Campbell 05/14/04 08:56:55 AM EDT

    Hi,
    If you are running ColdFusion MX 6.1 Enterprise edition, where would you copy the FOP files too? Copying to "C:\JRun4\servers\cfusion\cfusion-ear\cfusion-war\WEB-INF\cfusion\lib" and then using the JRun admin console to add FOP to the classpath results in the server not being able to restart. As a matter of fact, on Win XP, I''ve had to reinstall JRun/Coldfusion. Any help would be appreciated.
    Thanks,
    Bob

    Abhijit 05/12/04 07:06:06 PM EDT

    FOP should work with iPlanet and BEA Weblogic. The FOP.jar file comes bundled with Cocoon, and Cocoon works fine on iPlanet and Weblogic. See Cocoon 1.8 or later installation Notes at http://www.aoindustries.com/docs/cocoon-1.8/install.html

    Eric Gonzalez 05/12/04 04:06:03 PM EDT

    Does FOP work on IPlanet''s (SunOne) server or BEA WebLogic? I know FOP is java, which should have all necessary classes included in the .jar file but you could never be too sure.

    Tony 05/12/04 02:32:23 PM EDT

    Will all this work ONLY with Apache?
    Will this work under Iplanet/SunOne or does SunOne have a product/plugin similar to this?

    Thanks :)
    Tony

    IoT & Smart Cities Stories
    CloudEXPO | DevOpsSUMMIT | DXWorldEXPO are the world's most influential, independent events where Cloud Computing was coined and where technology buyers and vendors meet to experience and discuss the big picture of Digital Transformation and all of the strategies, tactics, and tools they need to realize their goals. Sponsors of DXWorldEXPO | CloudEXPO benefit from unmatched branding, profile building and lead generation opportunities.
    DXWorldEXPO LLC announced today that Big Data Federation to Exhibit at the 22nd International CloudEXPO, colocated with DevOpsSUMMIT and DXWorldEXPO, November 12-13, 2018 in New York City. Big Data Federation, Inc. develops and applies artificial intelligence to predict financial and economic events that matter. The company uncovers patterns and precise drivers of performance and outcomes with the aid of machine-learning algorithms, big data, and fundamental analysis. Their products are deployed...
    All in Mobile is a place where we continually maximize their impact by fostering understanding, empathy, insights, creativity and joy. They believe that a truly useful and desirable mobile app doesn't need the brightest idea or the most advanced technology. A great product begins with understanding people. It's easy to think that customers will love your app, but can you justify it? They make sure your final app is something that users truly want and need. The only way to do this is by ...
    Digital Transformation and Disruption, Amazon Style - What You Can Learn. Chris Kocher is a co-founder of Grey Heron, a management and strategic marketing consulting firm. He has 25+ years in both strategic and hands-on operating experience helping executives and investors build revenues and shareholder value. He has consulted with over 130 companies on innovating with new business models, product strategies and monetization. Chris has held management positions at HP and Symantec in addition to ...
    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...
    The challenges of aggregating data from consumer-oriented devices, such as wearable technologies and smart thermostats, are fairly well-understood. However, there are a new set of challenges for IoT devices that generate megabytes or gigabytes of data per second. Certainly, the infrastructure will have to change, as those volumes of data will likely overwhelm the available bandwidth for aggregating the data into a central repository. Ochandarena discusses a whole new way to think about your next...
    Cell networks have the advantage of long-range communications, reaching an estimated 90% of the world. But cell networks such as 2G, 3G and LTE consume lots of power and were designed for connecting people. They are not optimized for low- or battery-powered devices or for IoT applications with infrequently transmitted data. Cell IoT modules that support narrow-band IoT and 4G cell networks will enable cell connectivity, device management, and app enablement for low-power wide-area network IoT. B...
    The hierarchical architecture that distributes "compute" within the network specially at the edge can enable new services by harnessing emerging technologies. But Edge-Compute comes at increased cost that needs to be managed and potentially augmented by creative architecture solutions as there will always a catching-up with the capacity demands. Processing power in smartphones has enhanced YoY and there is increasingly spare compute capacity that can be potentially pooled. Uber has successfully ...
    SYS-CON Events announced today that CrowdReviews.com has been named “Media Sponsor” of SYS-CON's 22nd International Cloud Expo, which will take place on June 5–7, 2018, at the Javits Center in New York City, NY. CrowdReviews.com is a transparent online platform for determining which products and services are the best based on the opinion of the crowd. The crowd consists of Internet users that have experienced products and services first-hand and have an interest in letting other potential buye...
    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...