Using DDX instructions with ColdFusion

Although you can type DDX instructions directly in ColdFusion, typically you use an external DDX file. A DDX file is basically an XML file with a DDX extension (for example, merge.ddx). You can use any text editor to create a DDX file. The DDX syntax requires that you enclose the instructions within DDX start and end tags. In the following example, the PDF element provides instructions for merging two PDF source files (Doc1 and Doc2) into a result file (Out1):

<?xml version="1.0" encoding="UTF-8"?> 
<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"> 
<PDF source="Doc1"/> 
<PDF source="Doc2"/> 
</PDF> 
</DDX>

In ColdFusion, you verify the source DDX file with the IsDDX function:

<!--- The following code verifies that the DDX file exists and the DDX instructions are 
    valid. ---> 
<cfif IsDDX("merge.ddx")>

To implement the DDX instructions in ColdFusion, you create two structures: an input structure that maps the DDX input instructions to the PDF source files, and an output structure that maps the DDX output instructions to a PDF output file,

The following code maps two files called Chap1.pdf and Chap2.pdf to the Doc1 and Doc2 sources that you defined in the DDX file:

<!--- This code creates a structure for the input files. ---> 
<cfset inputStruct=StructNew()> 
<cfset inputStruct.Doc1="Chap1.pdf"> 
<cfset inputStruct.Doc2="Chap2.pdf">

The following code maps the output file called twoChaps.pdf to the Out1 result instruction that you defined in the DDX file:

<!--- This code creates a structure for the output file. ---> 
<cfset outputStruct=StructNew()> 
<cfset outputStruct.Out1="twoChaps.pdf">

To process the DDX instructions, you use the processddx action of the cfpdf tag, in which you reference the DDX file, the input structure, and the output structure, as the following example shows:

<cfpdf action="processddx" ddxfile="merge.ddx" inputfiles="#inputStruct#" 
    outputfiles="#outputStruct#" name="myBook">

The name attribute creates a variable that you can use to test the success or failure of the action. If the action is successful, ColdFusion generates an output file with the name and location specified in the output structure. The following code returns a structure that displays a success, reason for failure, or failure message (if the reason is unknown) for each output file, depending on the result:

<cfdump var="#myBook#">

The previous example performs the same task as the merge action in ColdFusion, as the following example shows:

<cfpdf action="merge" destination="twoChaps.pdf" overwrite="yes"> 
    <cfpdfparam source="Chap1.pdf"> 
    <cfpdfparam source="Chap2.pdf"> 
</cfpdf> 
</cfif>

In this situation, it makes more sense to use the merge action because it is easier. DDX is useful when you have to perform tasks that you can’t perform with other actions in the cfpdf tag, or you require more control over specific elements.