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 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):

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

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:

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

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:

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:

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

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:

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:

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:

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:

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:

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:

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

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:

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

Setting the initial view of a PDF document

To set the initial view of a PDF document, use the InitialViewProfile DDX element. Setting the initial view determines how the PDF output file is displayed on the screen when it is first opened in Adobe Acrobat Reader. You reference the InitialViewProfile by using the InitialView attribute of the PDF result element, as the following example shows:

In this example, the first time the PDF document is displayed in Acrobat Reader, the document is opened to page two and the bookmark panel is displayed. The magnification of the document is adjusted to fit the page.
For more information on IntialViewProfile settings, see the Adobe LiveCycle Assembler Document Description XML Reference.

Adding text-string watermarks

You use the processddx action with the Background or Watermark DDX elements to create a text-string watermark. Background elements appear in the background (behind the contents of the page); Watermark elements display in the foreground (over the contents of the page). The syntax for both the elements is the same.
The following example shows the DDX page for using the text string "DRAFT" as a watermark. The watermark appears on every page of the output file. By default, the watermark appears in the middle of the page. In this example, the watermark is rotated 30 degrees:

The following example shows how to add different backgrounds on alternating pages. The verticalAnchor attribute displays the background text at the top of the page:

Instead of applying watermarks to the entire output file, you can apply them to individual source files. The following example applies a different background to the first three chapters of a book. The fourth chapter has no background:

For more information on using DDX instructions to create watermarks, see the Adobe LiveCycle Assembler Document Description XML Reference.

Extracting text from a PDF document

You can use the DocumentText DDX element to return an XML file that contains the text in one or more PDF documents. As with the PDF element, you specify a result attribute the DocumentText element and enclose one or more PDF source elements within the start and end tags, as the following example shows:

The following code shows the CFM page that calls the DDX file. Instead of writing the output to a PDF file, you specify an XML file for the output:

The XML file conforms to a schema specified in doctext.xsd.
When you specify more than one source document, ColdFusion aggregates the pages into one file. The following example shows the DDX code for combining a subset of pages from two documents into one output file: