Manipulates existing PDF documents. The following list describes some of the tasks you can perform with the cfpdf tag:
ColdFusion 8: Added this tag.
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"
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
"> 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 if directory is specified:
order = "name|time"one of the following if <cfpdfparam ...> is specified:
name = "PDF document variable name
" destination = "PDF output file pathname
" optional 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"> Write a PDF document to an output file <cfpdf required action = "write" destination = "PDF output file pathname
"source = "
absolute or relative pathname to a PDF file|PDF document variable
|cfdocument variable
" 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">
cfdocument, cfdocumentsection, cfpdfform, cfpdfformparamUsage, cfpdfparam, cfpdfsubform, cfprint, IsDDX, IsPDFFile, IsPDFObject, "Assembling PDF Documents" in the ColdFusion Developer's Guide
Attribute |
Action |
Req/Opt |
Default |
Description |
---|---|---|---|---|
action |
N/A |
Optional |
processddx |
Action to take:
|
ascending |
merge |
Optional |
no |
Order in which the PDF files are sorted:
Applicable only when you specify the directory attribute. |
copyFrom |
addWatermark |
Optional |
|
Pathname of the PDF document from which to use the first page as a watermark |
ddxfile |
processddx |
Required |
|
Pathname of the DDX file, or a string with DDX instructions |
destination |
addWatermark deletePages merge protect removeWatermark setInfo thumbnail write |
Required for the write action Optional for all other actions |
|
Pathname of the modified PDF document. If the destination file exists, you must set the overwrite attribute to yes. If the destination file does not exist, ColdFusion creates the file, if the parent directory exists. You can specify the destination attribute or the name attribute, but not both. For the thumbnail action, the destination is the directory path where the images are written. If you specify a relative pathname to the destination directory, the destination directory is relative to the template directory. If you do not specify a destination directory, ColdFusion creates a directory called thumbnails in the directory in the template directory. |
directory |
merge |
Optional |
|
Directory of the PDF documents to merge. You must specify either the directory attribute or the source attribute. If you specify the directory attribute, ColdFusion orders the documents by filename in descending order, by default. To change the order of the files, use the order attribute. |
encrypt |
protect |
Optional |
RC4_128 (Acrobat 5.0 or higher) |
Encryption type for the PDF output file:
For more information, see Encryption for PDF documents. |
flatten |
write |
Optional |
no |
Applies to forms created in Acrobat only (not forms created in LiveCycle); specifies whether interactivity is turned off:
|
foreground |
addWatermark |
Optional |
no |
Placement of the watermark on the page:
|
format |
thumbnail |
Optional |
jpg |
File type of thumbnail image output:
|
image |
addWatermark |
Optional |
|
Image used as a watermark. You can specify a pathname, a variable that contains an image file, or a ColdFusion image variable. |
imagePrefix |
thumbnail |
Optional |
If the source is a pathname, the filename is used as the prefix; otherwise thumbnail is the prefix |
Prefix used for each image thumbnail file generated. The image filenames use the format: imagePrefix_page_n.format. For example, the thumbnail for page 1 of a document with the imagePrefix attribute set to myThumbnail is myThumbnail_page_1.jpg. |
info |
setInfo |
Required |
|
Structure variable for relevant information, for example, "#infoStruct#". You can specify the Author, Subject, Title, and Keywords for the PDF output file. |
inputFiles |
processddx |
Required |
|
Structure that maps the PDF source files to the input variables in the DDX file, or a string of elements and their pathname. |
isBase64 |
addWatermark |
Optional |
no |
Valid only when the image attribute is specified. Specifies whether the image used as a watermark is in Base64 format:
|
keepBookmark |
merge |
Optional |
no |
Specifies whether bookmarks from the source PDF documents are retained in the merged document:
|
name |
addWatermark deletePages getInfo merge processddx protect read removeWatemark write |
Required: getInfo processddx read Optional: addWatermark deletePages merge protect removeWatermark write |
|
PDF document variable name, for example, If the source is a PDF document variable, you cannot specify the name attribute again; you can write the modified PDF document to the destination. You can specify the destination attribute or the name attribute, but not both. For the processddx action, the name represents the structure that is populated with the success or failure of the output variables. |
newOwnerPassword |
protect |
Optional (see Description) |
|
Password used to set permissions on a PDF document. To change the default permissions, you must specify the newOwnerPassword attribute. For more information, see PDF document passwords. |
newUserPassword |
protect |
Optional (see Description) |
|
Password used to open PDF document. You must specify either the newUserPassword attribute or a newOwnerPassword attribute; if you specify both, the passwords must differ. For more information, see PDF document passwords. |
opacity |
addWatermark |
Optional |
3 |
Opacity of the watermark. Valid values are integers in the range 0 (transparent) through 10 (opaque). |
order |
merge |
Optional |
time |
Order in which the PDF documents in the directory are merged:
By default, ColdFusion merges the files in descending order (for example, from Z to A). To change this, set the ascending attribute to yes. |
outputFiles |
processddx |
Required |
|
Structure that contains the output files in the DDX file or string as keys and the pathname to the result file as the value. |
overwrite |
addWatermark deletePages merge protect removeWatermark setInfo thumbnail write |
Optional |
no |
Specifies whether PDF output overwrites the destination file:
For the thumbnail action, specifies whether to overwrite the destination directory. If the directory exists, the thumbnails are not generated unless overwrite is set to yes. |
pages |
addWatermark deletePages merge removeWatermark |
Required: deletePages Optional: addWatermark merge removeWatermark thumbnail |
all |
Page or pages in the source PDF document on which to perform the action. You can specify multiple pages and page ranges as follows: "1,6-9,56-89,100, 110-120". For the removeWatermark action, the pages attribute applies only to the watermark type. ColdFusion ignores duplicate pages and numbers greater than the total page count. |
password |
addWatermark deletePages getInfo merge protect read removeWatermark setInfo thumbnail write |
Optional |
|
Owner or user password of the source PDF document, if the document is password-protected. |
permissions |
protect |
Optional |
All |
Type of permissions on the PDF document:
Except for All or None, you can specify a comma-separated list of permissions. To set permissions, you must also set the newOwnerPassword attribute. |
position |
addWatermark |
Optional |
|
Position on the page where the watermark is placed. The position represents the top-left corner of the watermark. Specify the x and y coordinates; for example "50,30". |
resolution |
thumbnail |
Optional |
high |
Image quality used to generate thumbnail images:
|
rotation |
addWatermark |
Optional |
|
Degree of rotation of the watermark image on the page, for example, "30". |
saveOption |
write |
Optional |
full |
Save options for the PDF output:
|
scale |
thumbnail |
Optional |
25 |
Size of the thumbnail relative to the source page. The value represents a percentage from 1 through 100. |
showOnPrint |
addWatermark |
Optional |
no |
Specify whether to print the watermark with the PDF document:
|
source |
addWatermark deletePages getInfo merge protect read removeWatermark setInfo thumbnail write |
Required (see Usage section for merge) |
|
PDF document used as the source. The source can be one of the following:
|
stopOnError |
merge |
Optional |
no |
Valid only if the directory attribute is specified. If the specified directory contains files other then ColdFusion-readable PDF files, ColdFusion either stops merge process or continues.
|
transparent |
thumbnail |
Optional |
no |
(format="png" only) Specifies whether the image background is transparent or opaque:
|
version |
write |
Optional |
|
Version of the PDF used to write the document:
For more information, see PDF versions. |
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.
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:
Task |
Attributes |
Example |
---|---|---|
Overwrite a source PDF file |
Specify the PDF file pathname as the source and do not specify a destination. |
<cfpdf action="addWatermark" source="myPDF" image="myImage.jpg"> |
Write a PDF document in memory to a file |
Specify the PDF variable as the source and a PDF file pathname for the destination. |
<cfpdf action="addWatermark" source="myPDF" image="myImage.jpg" destination="outputFile.pdf"> |
Write a PDF document to a new file |
Specify a PDF file pathname as the source and a different PDF file pathname as the destination. |
<cfpdf action="addWatermark" source="sourceFile.pdf" image="myImage.jpg" destination="outputFile.pdf"> |
Write a PDF file to a PDF variable |
Specify the PDF file pathname as the source and a PDF variable name. |
<cfpdf action="addWatermark" source="sourceFile.pdf" image="myImage.jpg" name="myPDF"> |
Overwrite a PDF document in memory |
Specify the PDF variable name as the source and do not specify a destination. |
<cfpdf action="addWatermark" source="myPDF" image="myImage.jpg"> |
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.
Use the cfprint tag to print PDF documents. Markups, such as sticky notes, comments, and editorial revisions, are not printed with the document.
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. 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 ColdFusion Developer's Guide.
<cfpdf action="deletePages" source="c:\myBook.pdf" pages="1,16-32,89,100-147" destination="myLittleBook.pdf">
<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#">
The following table describes the information elements you can retrieve with the getinfo action:
Element |
Example |
Description |
---|---|---|
Application |
Acrobat PDFMaker 7.0.7 for Word |
Application used to create the PDF document. This value is read-only. |
Author |
Harper Lee |
Author of the PDF document. You can specify a text string with the setInfo action. |
CenterWindowOnScreen |
[empty string] |
Display setting for initial view of the PDF document. To change this setting, use the processddx action with the InitialViewProfile DDX element. |
ChangingDocument |
Not Allowed |
Permissions assigned for editing the PDF content. To change this setting, use the permissions attribute with the protect action. |
Commenting |
Allowed |
Permissions assigned for adding comments to the PDF document. To change this setting, use the permissions attribute with the protect action. |
ContentExtraction |
Allowed |
Permissions assigned for extracting content from the PDF document. To change this setting, use the permissions attribute with the protect action. |
CopyContent |
Allowed |
Permissions assigned for copying content from the PDF document. To change this setting, use the permissions attribute with the protect action. |
Created |
D:20061121155226-05'00' |
System-generated creation date of the PDF document. You can specify a text string with the setInfo action. |
DocumentAssembly |
Not Allowed |
Permissions assigned for merging the PDF document with other PDF documents. To change this setting, use the permissions attribute with the protect action. |
Encryption |
Password Security |
Specifies whether the PDF file is password-protected. To change the encryption algorithm, or add a password, use the protect action. |
FilePath |
C:\ColdFusion\wwwroot\lion\myDoc.pdf |
Absolute pathname for the PDF file. This value is read-only. |
FillingForm |
Allowed |
Permissions assigned for entering data in form fields. To change this setting, use the permissions attribute with the protect action. |
FitToWindow |
[empty string] |
Display setting for initial view of the PDF document. To change this setting use the processddx action with the InitialViewProfile DDX element. |
HideMenubar |
[empty string] |
Display setting for initial view of the PDF document. To change this setting, use the processddx action with the InitialViewProfile DDX element. |
HideToolbar |
[empty string] |
Display setting for initial view of the PDF document. To change this setting, use the processddx action with the InitialViewProfile DDX element. |
HideWindowUI |
[empty string] |
Display setting for initial view of the PDF document. To change this setting, use the processddx action with the InitialViewProfile DDX element. |
Keywords |
marketing,sales,production |
Keywords specified for searches in the PDF document. You can specify a comma-separated list of keywords with the setInfo action. |
Language |
EN-US |
Language version used to create the source file for the PDF document. This value is read-only. |
Modified |
D:20061121155226-06'00' |
System-generated timestamp for when the PDF file was last modified. You can specify a text string with the setInfo action |
PageLayout |
OneColumn |
Display setting for the initial view of the PDF document. To change this setting, use the processddx action with the InitialViewProfile DDX element. |
Printing |
Allowed |
Permissions assigned for printing the document. To change this setting, use the permissions attribute with the protect action. |
Producer |
Acrobat Distiller 7.0.5 (Windows) |
Version of Acrobat Distiller used to generate the PDF document. This value is read-only. |
Properties |
[empty string] |
This value is read-only. |
Secure |
Not Allowed |
Display setting that shows whether the PDF document is password protected. |
ShowDocumentsOption |
[empty string] |
Display setting for initial view of the PDF document. To change this setting, use the processddx action with the InitialViewProfile DDX element. |
ShowWindowsOption |
[empty string] |
Display setting for initial view of the PDF document. To change this setting, use the processddx action with the InitialViewProfile DDX element. |
Signing |
Allowed |
Permissions for allowing electronic signatures to the PDF document. To change this setting, use the permissions attribute with the protect action. |
Subject |
Product Marketing |
The subject assigned to the PDF document. You can specify a text string with the setInfo action. |
Title |
Chapter 1: Getting Started |
The title assigned to the PDF document. You can specify a text string with the setInfo action. |
TotalPages |
25 |
Total pages in the PDF document. This value is read-only. |
Trapped |
[empty string] |
Indicates whether trapping is applied to the PDF document. Trapping is used in printing to eliminate gaps between two adjoining ink colors. You can specify a text string with the setInfo action. |
Version |
1.6 |
Version of the Adobe PDF generator used to create the PDF document. To change this setting use the version attribute with the write action. For more information, see PDF versions. |
<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" overwrite="yes">
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 ColdFusion Developer's Guide.
ColdFusion provides a subset of LiveCycle Assembler functionality. To determine whether you can perform the 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.
The following table lists the DDX elements that ColdFusion supports:
About |
Author |
Background |
Center |
DatePattern |
DDX |
DocumentInformation |
DocumentText |
Footer |
Header |
InitialViewProfile |
Keyword |
Keywords |
Left |
MasterPassword |
Metadata |
NoBookmarks |
OpenPassword |
PageLabel |
Password |
PasswordAccessProfile |
PasswordEncryptionProfile |
PDF (see Note) |
PDFGroup |
Permissions |
Right |
StyledText |
StyleProfile |
Subject |
TableOfContents |
TableOfContentsEntryPattern |
TableOfContentsPagePattern |
Title |
Watermark |
|
|
The following table lists the DDX elements that ColdFusion excludes:
ArtBox |
AttachmentAppearance |
Bookmarks |
BlankPage |
BleedBox |
Comments |
Description |
FileAttachments |
FilenameEncoding |
LinkAlias |
Links |
NoBackgrounds |
NoComments |
NoFileAttchments |
NoFooters |
NoForms |
NoHeaders |
NoLinks |
NoPageLabels |
NoThumbnails |
NoWatermarks |
NoXFA |
PageMargins |
PageSize |
PageRotation |
PageOverlay |
PageUnderlay |
PDFsFromBookmarks |
Transform |
TrimBox |
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:
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 ColdFusion Developer's Guide.
When you use the protect action, you must 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, you must 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.
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:
ColdFusion password |
Acrobat equivalent |
Description |
---|---|---|
User password |
Document Open password, user password |
Anyone who tries to open the PDF document must enter the password that you specify. A user password does not allow a user to change restricted features in the PDF document. |
Owner password |
Permissions password, master password |
Lets the person who enters the password restrict access to features in a PDF document. |
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">
The following table lists the permissions an owner can set for PDF documents:
Permissions |
Description |
---|---|
All |
There are no restrictions on the PDF document. |
AllowAssembly |
Users can add the PDF document to a merged document. |
AllowCopy |
Users can copy text, images, and other file content. This setting is required to generate thumbnail images with the thumbnail action. |
AllowDegradedPrinting |
Users can print the document at low-resolution (150 DPI). |
AllowFillIn |
Users can enter data into PDF form fields. Users can sign PDF forms electronically. |
AllowModifyAnnotations |
Users can add or change comments in the PDF document. |
AllowModifyContents |
Users can change the file content. Users can add the PDF document to a merged document. |
AllowPrinting |
Users can print the document at high-resolution (print-production quality). This setting is required for use with the cfprint tag. |
AllowScreenReaders |
Users can extract content from the PDF document. |
AllowSecure |
Users can sign the PDF document (with an electronic signature). |
None |
Users can view the document only. |
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:
Encryption algorithm |
Compatibility |
Description |
---|---|---|
AES_128 |
Adobe Acrobat 7.0 and later |
Advanced Encryption Standard (AES) specifies the Rijndael algorithm, a symmetric block cipher that can process data blocks of 128 bits. This is the highest encryption level. This encryption algorithm lets users do the following:
|
RC4_128M |
Adobe Acrobat 6.0 and later |
RC4 specifies the RSA Security software stream cipher for algorithms such as Secure Sockets Layer (SSL), to protect Internet traffic, and WEP, to secure wireless networks. This encryption algorithm lets users do the following:
|
RC4_128 |
Adobe Acrobat 5.0 and later |
RC4 128-bit encryption. This encryption algorithm lets users encrypt the document contents, but not the document metadata. |
RC4_40 |
Adobe Acrobat 3.0 and later |
RC4 40-bit encryption. This is the lowest encryption level. |
None |
|
The document is not encrypted. |
<cfif IsPDFFile("Book.pdf")> <cfpdf action="read" source="Book.pdf" name="myBook"> ... </cfif>
<cfpdf action="removeWatermark" source="Book.pdf" pages="1" destination="newBook.pdf" overwrite="yes">
<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">
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; 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
<cfpdf action="read" source="Book.pdf" name="myBook"> <cfpdf action="write" source="myBook" destination="myBook1.pdf" version="1.4">
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:
PDF version |
Compatibility |
---|---|
1.1 |
Acrobat and Adobe Reader 2 |
1.2 |
Acrobat and Adobe Reader 3 |
1.3 |
Acrobat and Adobe Reader 4 |
1.4 |
Acrobat and Adobe Reader 5 |
1.5 |
Acrobat and Adobe Reader 6 |
1.6 |
Acrobat and Adobe Reader 7 |
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">
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>