Adobe ColdFusion 8

Using DDX to perform advanced tasks

LiveCycle Assembler is a server-based application that processes DDX, a declarative markup language used to define PDF output files.

The processddx action lets you process DDX instructions without installing LiveCycle Assembler. In addition to all of the functionality available with the other cfpdf actions, you can use DDX instructions to perform advanced tasks, such as adding a generated table of contents to a PDF document, adding headers and footers with automatic page numbers, and creating groups of PDF documents to which you can apply formatting instructions.

ColdFusion does not provide complete LiveCycle Assembler functionality. For a list of DDX elements that you can access from ColdFusion, see "Supported DDX elements" in the CFML Reference.

For complete DDX syntax, see the Adobe LiveCycle Assembler Document Description XML Reference.

Using DDX instructions with ColdFusion

Although you can type DDX instructions directly in ColdFusion, typically you refer to 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.

Adding a table of contents

You use DDX instructions to add a generated table of contents page to the PDF output file. Generating a table of contents is useful if you are assembling documents from multiple sources. You can generate a table of contents that contains active links to pages in the assembled PDF document. The following code shows how to create DDX instructions to merge two documents and add a table of contents:

<?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="Title">
            <TableOfContents/>
            <PDF source="Doc1"/>
            <PDF source="Doc2"/>
    </PDF>
</DDX>

The TableOfContents element generates a table of contents from the PDF source elements that follow it. Order is important: in the previous example, the table of contents appears on a separate page after the Title and before Doc 1 and Doc 2. The table of contents contains entries from Doc 1 and 2, but not from the title page, because the title page precedes the table of contents in the order of instructions.

You do not reference the TableOfContents element on the corresponding ColdFusion page, as the following example shows:

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

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

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

<!--- This code processes the DDX instructions and generates the book. --->
<cfpdf action="processddx" ddxfile="makeBook.ddx" inputfiles="#inputStruct#"
    outputfiles="#outputStruct#" name="myBook">
</cfif>

ColdFusion generates a table of contents from the DDX instructions and inserts it in the PDF document in the location that you provided in the DDX file. By default, the table of contents contains active links to the top-level bookmarks in the merged PDF document.

You can change the default TableOfContents settings in the DDX file, as the following example shows:

<TableOfContents maxBookmarkLevel="infinite" bookmarkTitle="Table of Contents"
    includeInTOC="false">

Use the maxBookmarkLevel attribute to specify the level of bookmarks included on the table of contents page. Valid values are infinite or an integer. Use the bookmarkTitle attribute to add a bookmark to the table of contents page in the output file. The includeInTOC attribute specifies whether the bookmark title is included on the table of contents page.

For more information on the TableOfContents element, see the Adobe LiveCycle Assembler Document Description XML Reference.

Adding headers and footers

To add headers and footers to a PDF document, specify the Header and Footer elements in the DDX file. The following example specifies headers and footers for the PDF source called Doc2:

<?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="Title"/>
        <TableOfContents/>
        <PDF source="Doc2" >
            <Header>
                <Right>
                    <StyledText><p>Right-justified header text</p></StyledText>
                </Right>
                <Left>
                    <StyledText><p>Left-justified header text</p></StyledText>
                </Left>
            </Header>
            <Footer>
                <Center>
                    <StyledText><p>Centered Footer</p></StyledText>
                </Center>
            </Footer>
        </PDF>
    </PDF>
</DDX>

In this example, the Header and Footer elements apply only to Doc2 because they are contained within that PDF source start and end tags; they do not apply to the table of contents or to the title page, which precede the Header and Footer elements.

Formatting headers and footers

You use DDX instructions to perform the following tasks:

  • Add automatic page numbers to headers and footers
  • Use style profiles
  • Group documents in the PDF output file

Adding automatic page numbers

To add automatic page numbers, use the _PageNumber and _LastPagenumber built-in keys within the Header or Footer elements. The following code shows how to create footers with right-justified automatic page numbers:

<Footer>
    <Right>
        <StyledText>
            <p>Page <_PageNumber/> of <_LastPageNumber/></p>
        </StyledText>
    </Right>
</Footer>

The first page of the output file is numbered "Page 1 of n", and so on.

For more information on built-in keys, see the Adobe LiveCycle Assembler Document Description XML Reference.

Using style profiles

The previous example uses the StyledText element to define inline text formatting. To define styles that you can apply by reference, use the StyleProfile element. Style profiles let you apply a set of styles to different elements in the PDF output file. The following code shows how to define a style profile for the table of contents Header:

<StyleProfile name="TOCheaderStyle">
    <Header>
        <Center>
            <StyledText>
            <p color="red" font-weight="bold" font="Arial">Table of Contents</p>
            </StyledText>
        </Center>
    </Header>
</StyleProfile>

To apply the style profile, refer to the StyleProfile name by using the styleReference attribute of the Header element, as the following example shows:

<?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="Title"/>
    <TableOfContents>
        <Header styleReference="TOCheaderStyle"/>
    </TableOfContents>
        <PDF source="Doc1"/>
        <PDF source="Doc2"/>
        <PDF source="Doc3"/>
        <PDF source="Doc4"/>
    </PDF>

    <StyleProfile name="TOCheaderStyle">
    <Header>
        <Center>
            <StyledText>
            <p> color="red" font-weight="bold" font="Arial">Table of Contents</p>
            </StyledText>
        </Center>
    </Header>
    </StyleProfile>
</DDX>

Grouping PDF documents

To apply a style profile to a group of documents in the output PDF file, use the PDFGroup element. The following example shows how to create a group of chapters in the output file and apply a style profile to the Footer element for all of the documents in the group:

<?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">
    <PageLabel prefix="page " format="Decimal"/>
    <PDF source="Title"/>
    <TableOfContents>
        ...
    </TableOfContents>
    <PDFGroup>
        <Footer styleReference="FooterStyle" />
        <PDF source="Doc1"/>
        <PDF source="Doc2"/>
        <PDF source="Doc3"/>
        <PDF source="Doc4"/>
    </PDFGroup>
    </PDF>

<StyleProfile name="FooterStyle">
    <Footer>
        <Left>
            <StyledText>
            <p font-size="9pt"><i>CFML Reference</i></p>
            </StyledText>
        </Left>
        <Right>
            <StyledText>
            <p font-size="9pt">Page <_PageNumber/> of <_LastPageNumber/></p>
            </StyledText>
        </Right>
    </Footer>
    </StyleProfile>
</DDX>

For a complete example, see Using DDX instructions to create a book.