cfpdf

Description

Manipulates existing PDF documents. The following list describes some of the tasks you can perform with the cfpdf tag:

• Merge several PDF documents into one PDF document.

• Delete pages from a PDF document.

• Merge pages from one or more PDF documents and generate a new PDF document.

• Linearize PDF documents for faster web display.

• Remove interactivity from forms created in Acrobat® to generate flat PDF documents.

• Encrypt and add password protection to PDF documents.

• Generate thumbnail images from PDF documents or pages.

• Add or remove watermarks from PDF documents or pages.

• Retrieve information associated with a PDF document, such as the software used to generate the file or the author, and set information for a PDF document, such as the title, author and keywords.

• Create PDF portfolios

• Add and remove header/footer from PDF documents

• Optimize PDF documents

History

ColdFusion 8: Added this tag.

ColdFusion 9: Added new attributes: jpgdpi, maxBreadth, noAttachments, leftMargin, algo, noMetadata, noBookMarks, noJavaScripts, useStructure, noFonts, text, noComments, encodeAll,numberFormat, compressTIFFs, addQuads, rightMargin, topMargin, bottomMargin, noThumbnails, align, noLinks, maxLength, hires, hScale, overridepage, honourspaces, maxScale, package, vScale

Category

Data output tags

Syntax

Add a watermark to a PDF document 
<cfpdf 
    required 
    action = "addwatermark" 
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
        cfdocument variable" 
    one of the following: 
    copyfrom = "absolute or relative pathname to a PDF file from which the first page is 
    used as a watermark" 
    image = "absolute or relative pathname to image file|image variable used as a 
    watermark" 
    optional 
    foreground = "yes|no" 
    isBase64 = "yes|no" 
    opacity = "watermark opacity" 
    overwrite = "yes|no" 
    pages = "page or pages to add the watermark" 
    password = "user or owner password for the PDF source file" 
    position = "position on the page where the watermark is placed" 
    rotation = "degree of rotation of the watermark" 
    showonprint = "yes|no"> 
    \\one of the following: 
    destination = "PDF output file pathname" 
    name = "PDF document variable name" 
    image = "image file name to be used as the footer" 
    text = "text to be used in the footer" 
Add headers 
<cfpdf 
    required 
    action = "addheader" 
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
            cfdocument variable" 
    pages = "page or pages to add the footer" 
    optional 
    isBase64 = "yes|no" 
    overwrite = "yes|no" 
    password = "user or owner password for the PDF source file" 
    showonprint = "yes|no"> 
    align = "left|right|center" 
    leftmargin = "value of the header left marign" 
    rightmargin = "value of the header right margin" 
    numberformat = "LOWERCASEROMAN|NUMERIC|UPPERCASEROMAN" <!---used with either 
    _PAGENUMBER or _LASTPAGENUMBER---> 
    opacity = "header opacity" 
    topmargin = "value of the top margin of the header" 
    \\one of the following: 
    destination = "PDF output file pathname" 
    name = "PDF document variable name" 
    text = _PAGELABEL: add current page label|_LASTPAGELABEL: add last page label|      
            _PAGENUMBER: add current page number|_LASTPAGENUMBER: add last page 
            number \\text for the header. You can also add a normal text string. 
    image = "image file name to be used as the header"  
 
Add footer 
<cfpdf 
    required 
    action = "addfooter" 
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
            cfdocument variable" 
    pages = "page or pages to add the footer" 
    optional 
    isBase64 = "yes|no" 
    overwrite = "yes|no" 
 
    password = "user or owner password for the PDF source file" 
    showonprint = "yes|no"> 
    destination = "PDF output file pathname" 
    name = "PDF document variable name" 
    align = "left|right|center" 
    one of the following: 
    image = "image file name to be used as the footer" 
    text =         _PAGELABEL: add current page label|_LASTPAGELABEL: add last page label|      
            _PAGENUMBER: add current page number|_LASTPAGENUMBER: add last page 
            number \\text for the header 
    leftmargin = "value of the footer left marign" 
    rightmargin = "value of the footer right margin" 
    numberformat 
    opacity = "footer opacity" 
    bottommargin = "value of the bottom margin" 
Delete pages from a PDF document 
<cfpdf 
    required 
    action = "deletepages" 
    pages = "page or pages to delete" 
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
            cfdocument variable" 
    optional 
    overwrite = "yes|no" 
    password = "PDF source file password" 
        one of the following: 
    destination = "PDF output file pathname" 
    name = "PDF document variable name"> 
Delete headers and footers 
<cfpdf 
    required 
    action = "removeheaderfooter" 
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
        cfdocument variable" 
    optional 
    overwrite = "yes|no" 
    pages = "page or pages to add the watermark" 
    password = "user or owner password for the PDF source file"  
    one of the following: 
    destination = "PDF output file pathname" 
    name = "PDF document variable name" 
Retrieve information about a PDF document 
<cfpdf 
    required 
    action = "getinfo" 
    name = "structure variable name"  
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
        cfdocument variable" 
    optional 
    password = "PDF source file password"> 
 
Merge PDF documents into an output PDF file 
<cfpdf 
    required 
    action = "merge" 
    one of the following: 
    directory = "directory of PDF files to merge" 
    source = "comma-separated list of PDF source files|absolute or relative pathname  
        to a PDF file|PDF document variable|cfdocument variable" 
    <cfpdfparam> 
    \\required only when package is specified as true 
    order = "name|time" 
    one of the following if <cfpdfparam> is specified: 
    name = "PDF document variable name" 
    destination = "PDF output file pathname" 
    optional 
    package = "true|false" <!---create PDF packages if set to true. You can provide 
        description in cfpdfparam tag, such as <cfpdfparam file="filename desc="">---> 
    ascending = "yes|no" 
    keepBookmark = "yes|no" 
    overwrite = "yes|no" 
    pages = "pages to merge in PDF source file" 
    password = "PDF source file password" 
    stopOnError = "yes|no" 
    \\one of the following: 
    destination = "PDF output file pathname" 
    name = "PDF document variable name"> 
 
Use DDX instructions to manipulate PDF documents 
<cfpdf 
    required 
    ddxfile = "DDX filepath|DDX string" 
    inputfiles = "#inputStruct#" 
    outputfiles = "#outputStruct#" 
    name = "structure name"> 
    optional 
    action="processddx" 
 
Set passwords and encrypt PDF documnets 
<cfpdf 
    required 
    action = "protect" 
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
        cfdocument variable" 
        at least one of the following: 
    newUserPassword = "password" 
    newOwnerPassword = "password" 
        if newOwnerPassword is specified: 
    permissions = "All|AllowAssembly|AllowDegradedPrinting|AllowCopy|AllowFillIn|AllowModifyAnnotations| 
        AllowModifyContents|AllowPrinting|AllowScreenReaders|AllowSecure|None| 
        comma-separated list" 
    optional 
    destination = "PDF output file pathname" 
    encrypt = "RC4_40|RC4_128|RC4_128M|AES_128|none" 
    overwrite = "yes|no" 
    password = "source file password"> 
     
Name a PDF document variable 
<cfpdf 
    required 
    action = "read" 
    name = "PDF document variable name" 
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
        cfdocument variable" 
    optional 
    password = "PDF source file password"> 
 
Remove a watermark from a PDF document 
<cfpdf 
    required 
    action = "removeWatermark" 
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
        cfdocument variable" 
    optional 
    overwrite = "yes|no" 
    pages = "page or pages from which to remove the watermark" 
    password = "PDF source file password"> 
        one of the following: 
    destination = "PDF output file pathname" 
    name = "PDF document variable name" 
 
Set information about a PDF document 
<cfpdf 
    required 
    action = "setinfo" 
    info = "#structure variable name#" 
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
        cfdocument variable" 
    optional 
    destination = "PDF output file pathname" 
    overwrite = "yes|no" 
    password = "PDF source file password"> 
 
Generate thumbnails from pages in a PDF document 
<cfpdf 
    required 
    action = "thumbnail" 
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
        cfdocument variable" 
    optional 
    destination = "directory path where the thumbnail images are written" 
    format = "png|jpeg|tiff" 
    imagePrefix = "string used as a prefix in the output filename" 
    overwrite = "yes|no" 
    password = "PDF source file password"> 
    pages = "page or pages to make into thumbnails" 
    resolution= "low|high" 
    scale = "percentage between 1 and 100" 
    transparent = "yes|no"> 
    hires = "yes|no" 
    overridepage = "yes|no" 
    compresstiffs = "yes|no" 
    maxscale = "maximum scale of the thumbnail" 
    maxlength = "maximum length of the thumbnail" 
    maxbreadth = "maximum width of the thumbnail" 
 
Write a PDF document to an output file 
<cfpdf 
    required 
    action = "write" 
    source = "absolute or relative pathname to a PDF file|PDF document variable| 
        cfdocument variable" 
    \\one of the following 
    destination = "PDF output file pathname" 
    name = #PDF variable# <!---new variable support added now---> 
    optional 
    flatten = "yes|no" 
    overwrite = "yes|no" 
    password = "PDF source file password" 
    saveOption = "linear|incremental|full" 
    version = "1.1|1.2|1.3|1.4|1.5|1.6">  
    encodeall = "yes|no" 
 
Reduce the quality of a PDF document 
<cfpdf 
    required 
    action = "optimize" 
    source = "absolute or relative path of the PDF file|PDF document variable| 
            cfdocument variable"  
    algo = "bilinear|bicubic|nearest_neighbor" <!---algorithm for image      
            downsampling---> 
    pages = "*" <!----page numbers associated with the objects in the PDF document--->     
    optional 
    vscale= "Vertical scale of the image to be modified. Valid values are vscale>0" 
    hscacle="Horizontal scale of the image to be modified. Valid values are hscale<1" 
    destination = "PDF output file pathname" 
    name = "PDF document variable" 
    noattachments = "Discard all attachments" 
    nobookmarks = "Discard all bookmarks" 
    nocomments = "Discard all comments" 
    nofonts = "Discard all fonts" 
    nojavascript = "Discard all JavaScript actions" 
    nolinks = "Discard external cross-references" 
    nometadata = "Discard document information and metadata" 
    nothumbnails = "Discard embedded page thumbnails" 
    overwrite = "true" <!---Overwrite the specified object in the PDF document---> 
    password = "" <!--- PDF document password---> 
      
Extract text  
<cfpdf 
    required 
    action="extracttext" <!---extract all the words in the PDF.---> 
    source= "absolute or relative path of the PDF file|PDF document variable| 
            cfdocument variable" 
    pages = "*" <!----page numbers from where the text needs to be extracted from the 
                PDF document---> 
    optional 
    addquads = "add the position or quadrants for the text in the PDF" 
    overwrite = "true" <!---Overwrite the specified object in the PDF document---> 
    password = "" <!--- PDF document password---> 
    type = "string|xml" <!---format in which the text needs to be extracted---> 
    one of the following: 
    destination = "PDF output file pathname" 
    name = "PDF document variable" 
Extract image 
<cfpdf 
    required 
    action = "extractimage" <!---extract images and save it to a directory---> 
    source = "absolute or relative path of the PDF file|PDF document variable| 
            cfdocument variable" 
    pages = "*" <!---page numbers from where the images need to be extracted---> 
    optional 
    overwrite = "true|false" <!---overwrite any existing image when set to true---> 
    format = "png|tiff|jpg" <!---format in which the images should be extracted---> 
    imageprefix = "*" <!---the string that you want to prefix with the image name---> 
    password = "" <!--- PDF document password---> 
    destination = "PDF output file pathname" 
     
Page level transformations 
<cfpdf 
    required 
    action = "transform" 
    source = "absolute or relative path of the PDF file|PDF document variable| 
            cfdocument variable" 
    pages = "page or pages to be transformed" 
    optional 
    hscale = "value of the horizontal scale of the page" 
    overwrite = "yes|no" 
    password = "PDF source file password" 
    position = "x, y" <!---value in pixels---> 
    rotation = "0|90|180|270" 
    vscale = "length of the page to be transformed" 
    one of the following: 
    destination = ""Path of the directory where the PDF document will be saved" 
    name = "PDF document variable" 

See also

cfdocument, cfdocumentsection, cfpdfform, cfpdfformparam, cfpdfparam, cfpdfsubform, cfprint, IsDDX, IsPDFFile, IsPDFObject, Assembling PDF Documents in the Developing ColdFusion Applications

Attributes

Usage

You use the cfpdf tag to manipulate and assemble existing PDF documents. Although the cfpdf tag provides much of the functionality available in Acrobat, you cannot use this tag to generate a PDF document from another file format. To create PDF output from HTML and CFML content, use the cfdocument tag.

You cannot embed a cfpdf tag within a cfdocument tag or embed a cfdocument tag within a cfdpdf tag; however, you can write the output of a cfdocument tag to a variable and pass the variable to the cfpdf tag. The following example shows how to use the cfdocument tag to create a cover page and add it to a merged PDF document:

<!--- Use the cfdocument tag to create a cover page and write the output to a variable called 
    cfdoc. ---> 
<cfdocument format="PDF" name="cfdoc"> 
<html> 
<body> 
<h1>Here is a cover page</h1> 
</body> 
</html> 
</cfdocument> 
 
<!--- Use the cfpdf tag and cfpdfparam tags to merge individual PDF documents into a new PDF document called new.pdf. Notice that the cfdoc variable created by using the cfdocument tag is the source value of the first cfpdfparam tag. ---> 
<cfpdf action="merge" destination="/samtemp/pdfs/new.pdf" overwrite="yes"> 
    <cfpdfparam source="cfdoc"> 
    <cfpdfparam source="/samtemp/pdfs/pdf2.pdf"> 
    <cfpdfparam source="/samtemp/pdfs/pdf1.pdf"> 
</cfpdf>

You can use the cfpdf tag to assemble interactive PDF form files into a single PDF document and flatten forms created in Acrobat (by using the flatten attribute with the write action); however, to process PDF form data, use the cfpdfform and related tags. You cannot use the cfpdf tag to flatten forms created in Adobe LiveCycle Designer ES.

Reading and writing PDF files

The cfpdf tag provides several options for reading and writing PDF files. You can specify a PDF variable or a PDF file as the source, and you can write the output to a variable or to a file (but not both). The following table explains the read and write operations:

Working with PDF files in memory

ColdFusion gives you the option to write a PDF file to a variable by using the name attribute, which is useful if you want to perform multiple operations on a document before writing it to a file. However, this is practical for small files only because of memory requirements. If you are working with large PDF documents, write the PDF documents to files.

ColdFusion recommends that you do not specify the name attribute when you specify a variable as the source because it creates a copy, which increases processing. In most cases, this is unnecessary because you can reuse variables even after you write them to files.

Printing PDF documents

Use the cfprint tag to print PDF documents. Markups, such as sticky notes, comments, and editorial revisions, are not printed with the document.

addWatermark action

Use the addwatermark action to add a watermark to specified pages in a PDF document. You can add a watermark in one of the following ways:

• Use the first page of another PDF document as a watermark. ColdFusion overlays the copyfrom page on the source document, without enlarging the image.

• Specify an image file to use as a watermark.

• Specify an image in memory by using an image variable.

The following code shows how to use the first page of a PDF document as a watermark:

<cfpdf action="addWatermark" source="c:\myBook.pdf" copyFrom="e:\yourBook.pdf" 
    destination="ourBook.pdf" overwrite="yes">

By default, ColdFusion applies the watermark to all of the pages in the output file, with the watermark image centered on the page. The following code applies a JPEG image as a watermark to the first page of the output file:

<cfpdf action="addWatermark" source="Book.pdf" 
    image="../cfdocs/images/artgallery/paul01.jpg" destination="newBook.pdf" pages="1" 
    overwrite="yes">

To specify a ColdFusion image as a watermark, use the cfimage tag or Image functions. With ColdFusion 9, the addwatermark action also supports RGB and ARGB images, especially the images added using the cfimage tag and related functions. The following example converts an image to grayscale and applies it as a watermark to a PDF file:

<!--- Use the ImageNew function to create a ColdFusion image from a JPEG file. ---> 
<cfset myImage=ImageNew("../cfdocs/images/artgallery/jeff05.jpg")> 
 
<!--- Use the ImageGrayscale function to convert the image to grayscale in memory. ---> 
<cfset ImageGrayscale(myImage)> 
 
<!--- Specify the image variable to apply the grayscale image as a watermark in the Book.pdf file. Because the source and destination are the same and the overwrite attribute is set to yes, ColdFusion overwrites the source file. ---> 
<cfpdf action="addWatermark" source="Book.pdf" destination="Book.pdf" overwrite="yes" image="#myImage#">

For more information on ColdFusion images, see Creating and Manipulating ColdFusion Images in the Developing ColdFusion Applications.

addfooter

Use this action to add a footer in a PDF document. Specify the source where the PDF document is located and the destination where the new PDF document with the footer is saved, as shown in the following code snippet:

<cfpdf action = "addfooter" 
                source = "../myBook.pdf" 
                destination = "../myBookwithfooter.pdf" 
                image = "adobelogo.JPG" // Use this attribute to add an image in the 
                                            footer 
                align = "right"> // By default, the alignemnt is center

You can also specify an image or text that you have to insert in the footer along with various other attributes such as align, bottommargin, leftmargin, numberformat, and opacity.

addheader

Use this action to add header in a PDF document. Specify the source and destination for the PDF document and specify the text or image that you want to insert in the header, as shown in the following code:

<cfpdf action = "addheader" 
        source = "../myBook.pdf" 
        destination = "../myBookwithheader.pdf" 
        text = "Adobe" 
        align = "left">

deletePages action

Use the deletePages action to remove pages from a specified PDF document. You can specify a single page, a page range, or a comma-separated list of pages, as the following code shows:

<cfpdf action="deletePages" source="c:\myBook.pdf" pages="1,16-32,89,100-147" 
    destination="myLittleBook.pdf">

extracttext

Use the extracttext action to extract all words from the specified page numbers in the PDF document, as shown in the following code snippet:

<cfpdf action = "extracttext" source = "../myBook.pdf" pages = "5-20, 29, 80" destination = "../adobe/textdoc.txt"

extractimage

Use the extractimage action to extract all images from the specified page number in a PDF document, as shown in the following code snippet:

<cfpdf action = "extractimage" source = "../myBook.pdf" pages = "1-200" destination = "..\mybookimages" imageprefix = "mybook">

The images are extracted and saved in the directory that you specify in the destination attribute. You can specify a prefix for the images (imageprefix) being extracted, otherwise the system prefixes the image name similar to “cf+page number”. To save the images in a specific format, use the format attribute.

getInfo action

Use the getInfo action to extract information associated with the PDF document, such as the author, title, and creation date. You specify the name of the structure variable that contains the relevant data associated with the file, as the following code shows:

<cfpdf action="getInfo" source="myBook.pdf" name="PDFInfo"> 
<p><cfoutput>#PDFInfo.title#</cfoutput></p> 
<p><cfoutput>#PDFInfo.author#</cfoutput></p> 
<p><cfoutput>#PDFInfo.keywords#</cfoutput></p> 
<p><cfoutput>#PDFInfo.created#</cfoutput></p>

For a complete list of information elements, use the cfdump tag, as the following code shows:

<cfdump var="#PDFInfo#">

Note: To view the permissions for a PDF document that is password-protected, specify the user password, not the owner password. If you specify the owner password, all permissions are set to Allowed.

Reducing quality of PDF document

The optimize action is used to downsample images and discard unused objects in a PDF document.

optimize

To downsample images in a PDF document, the algos attribute is used with values bilinear, bicubic, and nearest_neighbour. The following code snippet generates a PDF after image downsampling:

<cfpdf action = "optimize" algo = "bicubic" source "..\myBook.pdf" name = #mybook#> 

You can also discard unused objects such as comments, JavaScripts, attachments, bookmarks, and metadata from your PDF document using the following attributes with optimize action:

<cfpdf action = "optimize" 
        noJavaScript 
        noThumbnails 
        noBookmarks 
        noComments 
        noMetadata 
        noFileAttachments 
        noLinks 
        nofonts>

Transforming pages in a PDF document

You can scale a page, specify the position, and rotation values for pages in a PDF document.

transform

The transform action has four attributes that define the size (hscale, vscale), position(position), and rotation (rotation) of a page. The following code snippet shows the usage:

<cfpdf action = "transform" 
        required 
        source = "..\myBook.pdf" 
        optional 
        destination = "..\new\myBook.pdf"> 
        hscale = ".5" 
        vscale = ".15" 
        position = "8, 10" 
        rotation = "180">

The value for rotation must be in steps (0, 90, 180, 270). If you specify any other value, the system generates an error.

PDF file information elements

The following table describes the information elements you can retrieve with the getinfo action:

merge action

Use the merge action to assemble PDF documents or pages from PDF source files into one output file. The following code shows how to merge all the PDF files in a directory:

<cfpdf action="merge" directory="c:\myPDFfiles" destination="oneBigFile.pdf" 
    overwrite="yes">

By default, ColdFusion adds the files in descending order by timestamp. The following code merges the source files in ascending order by filename:

<cfpdf action="merge" directory="c:\book" order="name" ascending="yes" 
    destination="c:\book\output1.pdf" overwrite="yes">

This is useful if the source files have logical names, such as Chap0.pdf, Chap1.pdf, Chap2.pdf, and so on.

By default, ColdFusion continues the merge process even if it encounters a file in the specified directory that is not a valid PDF document. To stop the merge process if the directory contains files other than valid PDF documents, set the stopOnError attribute to yes:

<cfpdf action="merge" directory="c:\bookfiles" destination="book.pdf" overwrite="yes" 
    order="name" ascending="yes" keepBookmark="yes" stopOnError="yes">

To create a PDF file from specific pages in a document, use the source attribute with the pages attribute. The following code creates a file from pages 1–5 of the source document:

<cfpdf action="merge" source="myBigBook.pdf" pages="1-5" destination="myShortBook.pdf" 
    overwrite="yes">

To merge several files into one document, specify the absolute pathnames of the files in a comma-separated list, as the following code shows:

<cfpdf action="merge" source="c:\PDFdocs\myBook\Chap1.pdf, 
    c:\PDFdocs\myBook\Chap2.pdf,c:\PDFdocs\myBook\Chap3,pdf" destination="myBook.pdf" 
    package = "true" overwrite="yes">

You can now create PDF packages using the package = "true" attribute with the merge action.

For more control over the order of files, to assemble files in different locations, and to extract pages from multiple PDF files, use the cfpdfparam tag with the merge action. For more information on merging PDF files, see Assembling PDF Documents in the Developing ColdFusion Applications.

processddx action

Use the proccessddx action to assemble PDF files by processing Document Description XML (DDX) instructions. DDX is a declarative markup language used by Adobe® LiveCycle® Assembler. You can use DDX instructions to perform advanced tasks, such as adding table of contents pages, headers and footers, automatic page numbers, and text-string watermarks to PDF documents.

ColdFusion provides a subset of LiveCycle Assembler functionality. To determine whether you can perform your tasks in ColdFusion or whether you have to purchase LiveCycle Assembler, see the tables in the following sections.

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

Supported DDX elements

The following table lists the DDX elements that ColdFusion supports:

Restricted DDX elements

The following table lists the DDX elements that ColdFusion excludes:

Simple DDX instructions

You can create DDX instructions in any text editor and save the file with a DDX extension. The following example shows the DDX instructions for merging several documents and generating a table of contents with bookmarks from the source PDF documents:

<?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 source="Doc3"/> 
</PDF> 
</DDX>

Processing DDX instructions in ColdFusion

The following code processes the DDX instructions in ColdFusion:

<!--- The following code verifies that the DDX file exists and the DDX instructions are valid. ---> 
<cfif IsDDX("Book.ddx")> 
 
    <!--- The following code maps the PDF source files to the PDF source variables in the 
    DDX file. ---> 
    <cfset inputStruct=StructNew()> 
    <cfset inputStruct.Title="Title.pdf"> 
    <cfset inputStruct.Doc1="Chap1.pdf"> 
    <cfset inputStruct.Doc2="Chap2.pdf"> 
    <cfset inputStruct.Doc3="Chap3.pdf"> 
 
    <!--- The following code maps the PDF output file to the PDF result variable in the DDX 
    file. ---> 
    <cfset outputStruct=StructNew()> 
    <cfset outputStruct.Out1="output.pdf"> 
 
    <!--- The following code process the DDX instructions in the Book.ddx file to generate 
    a merged document. ---> 
    <cfpdf action="processddx" ddxfile="Book.ddx" inputfiles="#inputStruct#" 
        outputfiles="#outputStruct#" name="ddxVar"> 
<cfelse> 
    <p>The DDX instructions are not valid.</p> 
</cfif> 
 
<!--- The following code displays a success or failure message. ---> 
<cfoutput>#ddxVar.Out1#</cfoutput>

The name attribute defines a variable that you use to determine the success or failure of the process. Use the cfoutput tag to display the success or failure message, as the previous example shows, or use the cfdump tag to display a structure:

<cfdump var="#ddxVar#">

This code returns the following information for each output file in the structure:

• “Successful”, if the file is assembled successfully.

• “Reason for failure”, if the file is not assembled successfully and the reason for failure is known.

• “Failure”, if the file is not assembled successfully and the reason for failure is not known.

Use the IsDDX function to determine whether a DDX file or set of instructions is valid.

For detailed examples, see Assembling PDF Documents in the Developing ColdFusion Applications.

protect action

Use the protect action to password-protect PDF output files, set permissions, and encrypt PDF output files.

When you use the protect action, set a newUserPassword or a newOwnerPassword. (You can set both, as long as the passwords differ.) When you assign a user password to a document, all users must use this password to open the PDF document. The following code adds a user password to a PDF document:

<cfpdf action="protect" source="Finances.pdf" destination="myFinances.pdf" 
    newUserPassword="keepOut">

To set the permissions on the output file, set the newOwnerPassword. A user who enters the owner password when accessing the PDF file is considered the owner of file. The following example shows how to set a new owner password:

<cfpdf action="protect" encrypt="AES_128"source="Book.pdf" destination="MysteryBook.pdf" 
    overwrite="yes" newOwnerPassword="pssst" permissions="AllowDegradedPrinting">

Because the permissions are set to AllowDegradedPrinting in this example, ColdFusion lets users print the document at 150 DPI, but prohibits all other actions. If a user tries to delete the file, for example, ColdFusion generates an error message indicates that the password was entered incorrectly or the permissions do not allow the action to be performed.

ColdFusion does not retain permissions: if you add a newUserPassword attribute, you also must set the permission explicitly.

To work with myVar, you specify newownerpw as the password.

PDF document passwords

A PDF document can have two kinds of passwords: a user password and an owner password. The following table describes the two types of ColdFusion passwords and their equivalents in Acrobat:

When you protect a PDF, your password changes to the one you provide. ColdFusion updates the variable’s saved password to the one you provide. However, if you provide both passwords, ColdFusion uses the owner password.

The following protects a PDF:

<cfpdf action="protect" source="myVar" password="oldpassword" 
    permissions="none" newuserpassword="newuserpw" 
    newownerpassword="newownerpw">

To get all the properties of the PDF, you do the following:

<cfpdf action="info" source="myVar" name="info">

To get only the properties allowed for the user, you do the following:

<cfpdf action="info" source="myVar" password=" newuserpw" name="info">

Permissions for PDF documents

The following table lists the permissions an owner can set for PDF documents:

Encryption for PDF documents

The encrypt attribute sets the type of encryption used for opening a password-protected document. By default, ColdFusion uses the RC4 128-bit encryption algorithm to encrypt PDF files. To change the encryption algorithm, use the encrypt attribute with the protect action. The following code encrypts the PDF output file with the AES algorithm:

<cfpdf action="protect" encrypt="AES_128" source="Book.pdf" destination="MysteryBook.pdf" 
    overwrite="yes" newOwnerPassword="pssst" permissions="AllowDegradedPrinting">

ColdFusion supports the following encryption algorithms:

read action

Use the read action to read the source PDF document into the name variable, as the following code shows:

<cfif IsPDFFile("Book.pdf")> 
    <cfpdf action="read" source="Book.pdf" name="myBook"> 
... 
</cfif>

removeWatermark action

Use the removewatermark action to remove a watermark from a PDF document or specified pages in a document. The following example removes a watermark from the first page of a PDF document and writes the output to a new file:

<cfpdf action="removeWatermark" source="Book.pdf" pages="1" destination="newBook.pdf" overwrite="yes">

removeheaderfooter action

Use this action to remove the header and footer from a PDF document or from specified pages in a document. The following example removes the header and footer from the entire document:

<cfpdf action = "removeheaderfooter" source="..\mybook.pdf" destination = "new.pdf">

setInfo action

Use the setinfo action to specify information associated with a PDF document to be saved with it. Create a structure that contains the relevant information. Use the info attribute of the cfpdf tag to refer to the structure. The following code shows the elements that you can modify by using the setInfo action:

<cfset PDFinfo=StructNew()> 
<cfset PDFinfo.Title="Make Way for Ducklings"> 
<cfset PDFinfo.Author="Donald Duck"> 
<cfset PDFinfo.Keywords="Huey,Dewy,Louie"> 
<cfset PDFinfo.Subject="Ducks"> 
 
<cfpdf action="setInfo" source="chap1.pdf" info="#PDFinfo#" destination="meta1.pdf" overwrite="yes">

thumbnail action

Use the thumbnail action to generate thumbnail images from the source PDF document.

If you do not specify a destination directory for the thumbnail files, ColdFusion creates a directory for the thumbnails in the directory where the CFM page is located. If you specify a filename as the source, the thumbnail directory name is a concatenation of the name of the source file and _thumbnails. For example, the following code generates a thumbnail image for each page in myBook.pdf and stores them in a directory called myBook_thumbnails:

<cfpdf action="thumbnail" source="myBook.pdf">

If the CFM page is located in the directory c:\myProject\genThumbnails.cfm, the pathname for the thumbnails directory is c:\myProject\myBook_thumbnails.

By default, ColdFusion generates thumbnail files in JPEG format and the images are scaled to 25% of the original.

You can specify individual pages within the source document to generate thumbnails. Also, you can change the size of the thumbnail; the resolution, the output format (JPEG, PNG, or TIFF); and the prefix used for the thumbnail filenames. The following code generates a low-resolution thumbnail from the first page of the source document that is scaled at 50% of the original size:

<cfpdf action="thumbnail" source="myBook.pdf" pages="1" destination="c:\myBook\images" 
    imagePrefix="Cover" format="png" scale="50" resolution="low">

The full output file pathname is as follows:

c:\myBook\images\Cover_page_1.png

Note: To generate thumbnail images, the permissions of the source document must include AllowCopy. For more information, see Permissions for PDF documents in cfpdf.

ColdFusion 9 release has introduced some new attributes for the thumbnail action:

• hires: You can set this attribute to true to extract high-resolution images from the page. If a document contains high-resolution images and you want to retain the resolution of the images, then this attribute is useful.

  For example:

  <cfpdf action="thumbnail" source="./WORK/myBook.pdf" destination="./WORK/Testing_CFPDF" overwrite="true" hires="yes">

• overridepage: If you set this attribute to true, the thumbnail generated does not adhere to the PDF page size, but to the image size that is present in that page. If the image is not present, the size is set to the maximum size of the page.

• compresstiffs: Use this attribute to compress the size of the thumbnail images. As the name of the attribute suggests, it is only valid for the TIFF format. Following is an example:

  <cfpdf action="thumbnail" source="C:\WORK\myBook.pdf" destination="C:\WORK\Testing_CFPDF" overwrite="true" hires="yes" format="tiff" compresstiffs="yes"> 

• maxscale : Use this attribute to specify an integer value for the maximum scale of the thumbnail images.

• maxlength: Use this attribute to specify an integer value of the maximum length of the thumbnail images.

• maxbreadth: Use this attribute to specify an integer value of the maximum width of the thumbnail.

  The following example illustrates the use of maxscale, maxlength, and maxbreadth:

  <cfpdf action="thumbnail" source="./WORK/myBook.pdf" destination="./WORK/Testing_CFPDF" overwrite="true" format="jpg" maxscale="3" maxlength="300" maxbreadth="200" hires="yes" scale="100">

  Note: Typically, the value of the scale attribute is set to ‘100’ when using the maxscale attribute.

write action

Use the write action to write the source PDF document, or the PDF document stored in memory as a variable, to a file. The following code converts a PDF file stored in memory to a different PDF version and writes the output to a new file:

<cfpdf action="read" source="Book.pdf" name="myBook"> 
<cfpdf action="write" source="myBook" destination="myBook1.pdf" 
    version="1.4">

You can now use either name or destination attributes with the write action. The name attribute takes the value as the PDF document variable. For example, you can write the preceding code snippet as:

<cfpdf action="read" source="Book.pdf" name="myBook"> 
<cfpdf action="write" source="myBook" name=#myBook# 
    version="1.4">

The new encodeall attribute encodes all the unencoded streams in the source. However, it does not discriminate between dumb encodings like LZW and encodings like flate, so only unencoded streams get flate encoded.

PDF versions

Change the PDF version so that users running an older version of Acrobat or Adobe Reader can open the file. The following table shows the compatibility between the PDF version and the corresponding Acrobat and Adobe Reader versions:

To linearize PDF documents for faster web display, set the saveOption attribute to linear, as the following code shows:

<cfpdf action="write" source="myBook" destination="myBook1.pdf" saveOption="linear" 
    overwrite="yes">

Do not use the linear save option if you have to maintain interactivity in PDF forms or if the PDF document is enabled for electronic signatures. To allow for electronic signatures, set the saveOption attribute to incremental, as the following code shows:

<cfpdf action="write" source="myDraft" destination="mySignedDoc.pdf" 
    saveOption="incremental" overwrite="yes">

Use the flatten attribute to flatten forms created in Acrobat:

<cfpdf action="write" source="myAcrobatForm.pdf" 
    destination="myFlatForm.pdf" flatten="yes" overwrite="yes">

Example

The following example generates thumbnail images from pages in a PDF document and links the thumbnail images to the pages in the PDF document:

<h3>PDF Thumbnail Demo</h3> 
 
<!--- Create a variable for the name of the PDF document. ---> 
<cfset mypdf="myBook"> 
<cfset thisPath=ExpandPath(".")> 
<!--- Use the getInfo action to retrieve the total page count for the 
    PDF document. ---> 
<cfpdf action="getInfo" source="#mypdf#.pdf" name="PDFInfo"> 
<cfset pageCount="#PDFInfo.TotalPages#"> 
 
<!--- Generate a thumbnail image for each page in the PDF source document, 
    create a directory (if it doesn't already exist) in the web root that is 
    a concatenation of the PDF source name and the word "thumbnails", and 
    save the thumbnail images in that directory. ---> 
<cfpdf action="thumbnail" source="#mypdf#.pdf" overwrite="yes" 
    destination="#mypdf#_thumbnails" scale=60>  
 
<!--- Loop through the images in the thumbnail directory and generate a link 
    from each image to the corresponding page in the PDF document. ---> 
<cfloop index="LoopCount" from ="1" to="#pageCount#" step="1"> 
    <cfoutput> 
        <!--- Click the thumbnail image to navigate to the page in the PDF 
                document. ---> 
        <a href="#mypdf#.pdf##page=#LoopCount#" target="_blank"> 
        <img src="#mypdf#_thumbnails/#mypdf#_page_#LoopCount#.jpg"></a> 
    </cfoutput> 
</cfloop>