Mantis and Jessamine

ColdFusion, DDX, and PDFs Part 1: Gotchas

Before getting into the details of styling PDF document components using DDX, I wanted to share two very big “gotchas” that Brian and I experienced:

1. When declaring the DDX element, make sure you copy it exactly, including the (seemingly) incorrect space in the schemaLocation.
2. When testing your DDX using the IsDDX() function, make sure that your server isn’t locking the file

Here’s the correct DDX element to use whenever you’re trying to create a valid DDX document instance:

<DDX xmlns="http://ns.adobe.com/DDX/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://ns.adobe.com/DDX/1.0/ coldfusion_ddx.xsd">

If you remove the space, IsDDX() will return false, and you’ll pull your hair out trying to create a minimal DDX that will work.

As for 2, we again discovered the file locking propensity of Windows 7 and Adobe’s Acrobat reader. Even if your PDF is downloaded from a web server, it’s quite possible to remain locked if it’s open. Whether testing with your dev server (especially a local machine) or a production server, make sure that when doing the tweak code/rerun PDF generation/view result cycle that you absolutely positively are not viewing, previewing, or have any possibility of keeping an open handle on the output PDF. If you do, once again IsDDX() will return false. Again you’ll want to pull out your hair in frustration as code that worked just a moment ago now refuses to regenerate a PDF.

ColdFusion, DDX, and PDFs Part 2: Styling a Table of Contents

As promised, experiences from working with Brian Hall on the ECU printable telephone directory.  We knew we want Adobe Acrobat (aka PDF) files to provide a reasonable platform-agnostic method of producing quality printed output.  One of the features that we wanted is a table of contents.  That’s reasonably easy using DDX, and you can see the DDX-101 version mentioned by Adobe and by the ever-popular ColdFusion Jedi .  Beyond the ability to create a table of contents, there’s not much out there about modifying the look and feel.  Hence the excitement when Brian was able to dig up the DDX reference manual.  It turns out that you actually do have control over the style of the table of contents even with the modified LiveCycle support within ColdFusion 9.0.1.

<cfsavecontent variable="myDDX">
<DDX xmlns="http://ns.adobe.com/DDX/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://ns.adobe.com/DDX/1.0/ coldfusion_ddx.xsd">
	<PDF result="Out1">
	<TableOfContents includeInTOC="false" bookmarkTitle="Table of Contents">
		<TableOfContentsEntryPattern applicableLevel="all" >
			<StyledText>
				<p font-family="Times New Roman" font-size="12pt">
					<_BookmarkTitle/>
					<Space/>
					<Space/>
					<leader leader-pattern="dotted"/>
					<Space/>
					<Space/>
					<_BookmarkPageCitation/>
				</p>
			</StyledText>
		</TableOfContentsEntryPattern>
	</TableOfContents>
	<PDFGroup>
		<PDF source="Doc1" />
		<PDF source="Doc2" />
	</PDFGroup>
	</PDF>
</DDX>
</cfsavecontent>
<cfif IsDDX(#myDDX#)>
	<cfset inputStruct = StructNew()>
	<cfset inputStruct.Doc1 = "FirstDocument.pdf">
	<cfset inputStruct.Doc2 = "SecondDocument.pdf">
	<cfset outputStruct = StructNew()>
	<cfset outputStruct.Out1 = "CombinedDocument.pdf">
	<cfpdf action="processddx" ddxfile="#myddx#" inputfiles="#inputStruct#" outputfiles="#outputStruct#" name="ddxVar">
	<cfdump var="#ddxVar#">
<cfelse>
	<cfoutput><p>NO, DDX IS NOT OK</p></cfoutput>
</cfif>

Above is a complete snippet, suitable for saving to a CFM file that will run completely. For it to function on your own ColdFusion instance, you’ll need the following:

• A PDF file with the file name FirstDocument.pdf
• A PDF file with the file name SecondDocument.pdf

Given these two files and the above code saved to a ColdFusion cfm file, you’ll get a new file generated called CombinedFile.pdf.  If you open this file with a PDF reader, you’ll see a table of contents page followed by the contents of your two PDFs.  You’ll also see a bookmark called “Table of Contents”.  The table of contents will have entries for your two PDFs; these entries can be clicked and you’ll go directly to that sub-document.

The reason for this blog post is not the part that takes individual PDFs and combines them (you can find that in the Adobe documentation), but the fact that you can actually style the ToC, not just accept the defaults (which for us was a plain-jane Courier font).  The key is discovering the TableOfContentsEntryPattern, leader, _BookmarkTitle, and _BookmarkPageCitation elements.  The TableOfContentsEntryPattern defines how each line in your ToC will look.  Within that is a StyledText element, which is necessary whenever you are using styled text within DDX.  Further, since you’re defining a single instance of an element that gets repeated by the LiveCycle engine, you need markers for the title and page number.  The title is the _BookmarkTitle and the page number is _BookmarkPageCitation.

The leader element is used for producing the stream of periods between the title and page number.  The leader element has a leader-pattern attribute, which can be:

This valuable information exists only in the DDX reference, without which you’re not going to be able to produce complex formats.

With the font size we were using, we needed a little space after the document title and before the page number.  The oh-so-useful Space element fit the bill exactly.  Finally, we added a couple of optional attributes to the TableOfContents: includeInToc (which means that the table of contents page itself is not included in the ToC) and bookmarkTitle (which is the text used for the bookmark that references the ToC).

Oh, and one final thing: almost all of the DDX examples I found used a file system file containing the DDX.  Big thanks to Raymond Camden for providing examples where cfsavecontext is used to have an inline version.  Make sure that you use the trim function on your context saved variable, or you’ll have (yet another!) instance of where IsDDX() will return false.

In Part 3, there will be additional formatting options we discovered through a combination of trial and error and combing the DDX documentation.  Until then, get some PDFs and have fun playing with these options.

Adobe LiveCycle 9.0 (ES2) DDX Reference

When trying to fully take advantage of Adobe Acrobat files using ColdFusion, you’re going to have to delve into the world of DDX. Although several bloggers have linked to the Adobe DDX reference so that ColdFusion programmers can get the full syntax, almost all of the links no longer work due to reorganization of Adobe’s web site. To help the ColdFusion community, I’m posting a live link to the PDF reference as of now:

http://help.adobe.com/en_US/livecycle/9.0/ddxRef.pdf

Because at some point this link will also suffer from bit rot, I’ve decided to make a copy available from this blog as well.

My coworker Brian Hall and I spent a considerable amount of time with Google, our dev laptops, and several ColdFusion bloggers / experts to make some PDFs generated from dynamic data. I’ll be posting our findings, including the not-seen-in-one place styling of an automatically generated table of contents using DDX in ColdFusion.

Although I don’t yet have my posts with how-tos ready, I do want to warn the ColdFusion folks out there to make sure to consult the documentation for (dis)allowed DDX elements. For instance, you may wish to view the list of elements supported in ColdFusion 9.0.1. If the previous link fails, look for the detailed information in the CFPDF tag reference.

CFinNC