You use the cfpdf tag actions to perform shortcuts to common PDF document assembly and manipulation.
Adding and removing watermark images
Use the addWatermark and removeWatermark actions to add and remove watermarks from PDF documents. You can create a watermark and apply it to a PDF document in one of the following ways:
- Use an image file as a watermark.
- Specify a variable that contains an image file.
- Specify a ColdFusion image.
- Use the first page of a PDF document as a watermark.
Note: You can also use the Watermark or Background DDX elements with the processddx action to create a text-string watermark. For more information, see Using DDX to perform advanced tasks. |
Using an image file as a watermark
The following example shows how to specify an image file as a watermark:
image="../cfdocs/images/artgallery/raquel05.jpg" destination="output.pdf" |
By default, ColdFusion centers the image on the page, sets the opacity of the image to 3 out of 10 (opaque), and displays the image in the background of each page in the output file. In the following example, ColdFusion displays the watermark in the foreground, offset 100 pixels from the left margin of the page and 100 pixels from the bottom margin of the page. Because the opacity is set to 1, the image does not obscure the page content.
image="../cfdocs/images/artgallery/raquel05.jpg" destination="output.pdf" |
For a complete list of attributes and settings, see the cfpdf tag in the CFML Reference.
With the ColdFusion 9 release, the addWatermark action now supports the rgb and argb formats also. The following example shows that if you set the parameters for a new image to rgb or argb and then use the cfpdf action=addwatermark, ColdFusion allows this action:
<cfset myImage = ImageNew("",200,200,"argb","gray")> |
Using a variable that contains an image file
You can specify a variable that contains an image as a watermark. The following example shows how to create a form from which the user can select an image:
as a watermark. ---> |
The processing page uses the image selected from the form as the watermark for a PDF file:
by using the input variable form.art. ---> |
Using a ColdFusion image as a watermark
You can specify a ColdFusion image as a watermark. You can extract an image from a database and manipulate the image in memory, but you don't have to write the manipulated image to a file. Instead, you can apply the manipulated image as a watermark in a PDF document.
In the following example, the first ColdFusion page extracts images from a database and populates a pop-up menu with the titles of the artwork:
<cfquery name="artwork" datasource="cfartgallery"> |
The action page generates a ColdFusion image from the selected file by using the cfimage tag. The ImageScaleToFit function resizes the image and applies the bicubic interpolation method to improve the resolution. To use the manipulated image as a watermark, specify the image variable, as the following example shows:
<cfif IsImageFile("../cfdocs/images/artgallery/#form.art#")> |
For more information on ColdFusion images, see Creating and Manipulating ColdFusion Images.
Creating a text image and using it as a watermark
You can use the ImageDrawText function to create a text image in ColdFusion and apply the image as a watermark, as the following example shows:
<cfset myImage=ImageNew("",500,500)> |
For more information on ColdFusion images, see Creating and Manipulating ColdFusion Images. For an example of using DDX elements to create a text-string watermark, see Adding text-string watermarks in Using DDX to perform advanced tasks.
Using a PDF page as a watermark
Use the copyFrom attribute to create a watermark from the first page of a PDF file and apply it to another PDF document. In the following example, ColdFusion creates a watermark from the first page of image.PDF, applies the watermark to the second page of artBook.pdf, and writes the output to a new file called output.pdf:
destination="output.pdf" overwrite="yes"> |
In this example, image.pdf appears in the background of the second page of artBook.pdf. ColdFusion does not change the size of the watermark image to fit the page. The page used as a watermark can contain text, graphics, or both.
Removing watermarks
Use the removeWatermark action to remove a watermark from one or more pages in a PDF document. The following example shows how to remove a watermark from the entire PDF document and write the document to a new output file:
<cfpdf action="removeWatermark" source="artBook.pdf" destination="noWatermark.pdf"> |
The following example shows how to remove a watermark from the first two pages of a PDF document and overwrite the source document:
overwrite="yes" pages="1-2"> |
Because the source and the destination are the same and the overwrite attribute is set to yes, ColdFusion overwrites the source file with the output file.
Optimizing PDF documents
To optimize a PDF document you can reduce the quality of the document. To reduce the quality of a PDF document you can either downsample the images or remove unused objects from the document.
To downsample images 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#> |
To discard unused objects such as comments, JavaScripts, attachments, bookmarks, and metadata from your PDF document using the following attributes with optimize action:
noJavaScript |
Optimizing page count using encodeall
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.
Example:
<cfpdf action=write source="./inputFiles/Source.pdf" destination="./outputFiles/Output.pdf" encodeAll="yes"> |
Adding and deleting headers and footers from a PDF
You can add a header and footer to a PDF document using the addheader and addfooter actions, as shown in the following snippet:
<cfpdf action = "addfooter" |
Specify the source where the PDF document is located and the destination where the new PDF document with the header and footer will be saved.
You can also specify an image or text that you need to insert in the footer along with various other attributes such as align, bottommargin, leftmargin, numberformat, and opacity.
To remove header and footer from a PDF document, use the removeheaderfooter action, as shown in the following snippet:
<cfpdf action = "removeheaderfooter" source="..\mybook.pdf" destination = "new.pdf"> |
Use this action to remove the header and footer from a PDF document or from specified pages in a document.
Extracting images and text
You can extract text and images from a PDF document using the extracttext and extractimage actions.
The extracttext action extracts 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" |
The extractimage action extracts 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.
Performing page level transformations
You can scale a page, specify the position, and rotation values for pages in a PDF document using the transform action. This 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. The value for rotation needs to be in steps (0, 90, 180, 270). If you specify any other value, the system generates an error.
source = "..\myBook.pdf" |
Deleting pages from a PDF document
Use the deletepages action to remove pages from a PDF document and write the result to a file. You can specify a single page, a page range (for example, "81-97"), or a comma-separated list of pages to delete, as the following example shows:
destination="abridged.pdf" overwrite="yes"> |
Protecting PDF files
Use the protect action to password-protect, set permissions, and encrypt PDF documents for security.
Setting passwords
ColdFusion supports two types of passwords: an owner password and a user password. An owner password controls the ability to change the permissions on a document. When you specify an owner password, you set permissions to restrict the operations users can perform, such as the ability to print a document, change its content, and extract content. The following code creates an owner password for a document:
destination="timesheet.pdf" overwrite="yes" permissions="AllowPrinting"> |
To password-protect a document, set the user password. A user password controls the ability to open a document. If you set a user password for a document, any person attempting to open the file is prompted to enter a password. The following example sets the user password for a document:
destination="myTimesheet.pdf"> |
In the previous example, no restrictions apply to the PDF document after the user enters the correct password. To restrict usage and password-protect a document, add a user password and an owner password. Use the owner password to set the permissions, as the following example shows:
source="timesheet.pdf" destination="myTimesheet.pdf" overwrite="yes" |
In the previous example, a person who enters the user password (openSesame) can print the document only. A person who enters the owner password (topSecret) is considered the owner of the document, has full access to the file, and can change the user permissions for that file.
Setting permissions on a PDF document
To set permissions on a PDF document, specify a newOwnerPassword. Conversely, you cannot set the newOwnerPassword without also setting the permissions attribute. Only an owner can change permissions or add passwords. For a list of permissions that an owner can set for PDF documents, see cfpdf in the CFML Reference.
Except for all or none, owners can specify a comma-separated list of permissions on a document, as the following example shows:
source="timesheet.pdf" newOwnerPassword="private" newUserPassword="openSesame" |
In this example, a user must enter the password openSesame before opening the PDF form. All users can print the document at any resolution, but only the owner can modify the document or change the permissions.
Encrypting PDF files
When you specify the protect action for a PDF file, ColdFusion encrypts the file with the RC4 128-bit algorithm by default. Depending on the version of Acrobat running on the ColdFusion server, you can set the encryption to protect the document contents and prevent search engines from accessing the PDF file metadata.
You can change the encryption algorithm by using the encrypt attribute. For a list of supported encryption algorithms, see cfpdf in the CFML Reference.
The following example changes the password encryption algorithm to RC4 40-bit encryption:
overwrite="yes" newOwnerPassword="paSSword1" newUserPassword="openSesame" |
To prevent ColdFusion from encrypting the PDF document, set the encryption algorithm to none, as the following example shows:
<cfpdf action="protect" source="confidential.pdf" encrypt="none" destination="public.pdf"> |
To decrypt a file, provide the owner or user password and write the output to another file. The following code decrypts the confidential.pdf file and writes it to a new file called myDocument.pdf:
destination="myDocument.pdf"> |
Managing PDF document information
To retrieve information stored with a source PDF document, such as the creation date, the application used to create the PDF document, and the name of the person who created the document, use the getInfo action. For a list of data elements, see PDF file information elements in the CFML Reference.
Use the setInfo action to specify information, such as the author, subject, title, and keywords associated with the output file. This information is useful for archiving and searching PDF documents. PDF document information is not displayed or printed with the document.
The following example shows how to set keywords for tax documents. The information is useful for assembling the documents based on the tax filing requirements for different business types (Sole Proprietor, Partnership, and S Corporation). Some business types share the same forms and documents. By setting the business type keywords for each document, you can store the documents in one directory and search them based on keyword values. The following code sets three keywords for the p535.pdf tax booklet:
<cfset taxKeys.keywords="Sole Proprietor,Partnership,S Corporation"> |
When you use the setInfo action, ColdFusion overwrites any existing information for that key-value pair. In the previous example, if the pc535.pdf document contained a keyword of "tax reference", ColdFusion overwrites that keyword with "Sole Proprietor, Partnership, S Corporation".
To retrieve all of the information associated with the tax file, use the cfdump tag with the getInfo action, as the following example shows:
<cfdump var="#taxInfo#"> |
To retrieve just the keywords for the PDF document, use this code:
<cfoutput>#taxInfo.keywords#</cfoutput> |
Using the name attribute with write action
You can now use the name attribute with <cfpdf action = "write"> and specify a variable name for your PDF document. For example:
<cfpdf action="write" source="myBook" name=#myBook# version="1.4"> |
This feature is available with both cfpdf and cfpdfform tags.
Merging PDF documents
ColdFusion lets you merge PDF documents in the following ways:
- Merge all of the PDF files in a specified directory.
- Merge a comma-separated list of PDF files.
- Merge individual PDF files, and pages within those files, explicitly, even if the source files are stored in different locations.
- Merge the contents of a PDF variable generated by the cfdocument tag or a cfpdf tag
- Create PDF packages
To merge the contents of a directory, use the merge action and specify the directory where the source PDF files are located, as the following example shows:
<cfpdf action="merge" directory="c:/BookFiles" destination="myBook.pdf" overwrite="yes"> |
By default, ColdFusion merges the source files in descending order by timestamp. You can control the order in which the PDF files are added to the book by setting the order and ascending attributes. The following code merges the files in ascending order according to the timestamp on the files:
<cfpdf action="merge" directory="c:/BookFiles" destination="myBook.pdf" order="name" |
By default, ColdFusion continues the merge process even if it encounters a file that is not a valid PDF document in the specified directory. To override this setting, set the stopOnError attribute to yes, as the following example shows:
<cfpdf action="merge" directory="c:/BookFiles" destination="myBook.pdf" order="time" |
You can merge a comma-separated list of PDF files. To do this merge, specify the absolute path for each file, as the following example shows:
source="c:\coldfusion\wwwroot\lion\Chap1.pdf,c:\coldfusion\wwwroot\lion\Chap2.pdf" |
For more control over which files are added to the merged document, use the cfpdfparam tag with the cfpdf tag. The cfpdfparam tag merges documents or pages from documents located in different directories into a single output file. When you use the cfpdfparam tag, the PDF files are added to the output file in the order they appear in the code. In the following example, the cover, title, and copyright pages are followed by the first five pages of the introduction, then all of the pages in Chapter 1, and then the first page followed by pages 80-95 in Chapter 2:
<cfdocument format="PDF" name="coverPage"> |
Because the keepbookmark attribute is set to yes, ColdFusion retains the bookmarks from the source documents in the output file.
Note: You cannot use the cfpdf tag to create bookmarks in a PDF document. |
Creating PDF Portfolios
You can now create PDF packages using the package = "true" attribute with the merge action:
<cfpdf action="merge" package="yes" destination="./myBook/adobetest.pdf" overwrite="yes"> |
Flattening forms created in Acrobat
Flattening forms involves removing the interactivity from the form fields. This action is useful for displaying form data and presenting it without allowing it to be altered. Use the write action to flatten PDF forms, as the following example shows:
destination="taxforms/flatForm.pdf" overwrite="yes"> |
Note: If you flatten a prefilled form created in Acrobat, ColdFusion flattens the form and removes the data from the form fields. When you specify a form created in Acrobat as a source file for merge action of the cfpdf tag, ColdFusion automatically flattens the form and removes data from the form fields, if the fields are filled in. ColdFusion does not support flattening forms created in LiveCycle. |
Linearizing PDF documents for faster web display
For efficient access of PDF files over the web, linearize PDF documents. A linearized PDF file is structured in a way that displays the first page of the PDF file in the browser before the entire file is downloaded from the web server. As a result linear PDF documents open almost instantly.
To linearize PDF documents, specify the saveOption attribute of the write action. The following example saves the output file in linear format:
overwrite="yes"> |
Note: Linearization can decrease performance when handling large documents. |
Generating thumbnail images from PDF pages
Use the thumbnail action to generate thumbnail images from PDF pages. If you specify only the source attribute with the thumbnail action, ColdFusion automatically creates a directory relative to the CFM page called thumbnails where it stores a generated JPEG image for each page in the document. The filenames are in the following format:
PDFdocumentName_page_n.JPG |
For example, assume that the source file in the following example has 100 pages:
<cfpdf action="thumbnail" source="myBook.pdf"> |
ColdFusion generates the following files and stores them in the thumbnails directory:
myBook_page_2.jpg |
If you specify a destination, ColdFusion does not create the thumbnails directory and stores the files in the specified directory instead. The following code generates a thumbnail image called myBook_page_1.jpg from the first page of myBook.pdf and stores it in a directory called images, which is relative to the CFM page:
<cfpdf action="thumbnail" source="myBook.pdf" pages="1" destination="images"> |
You change the prefix for the thumbnail filename and the change image file format to PNG or TIFF by specifying the imagePrefix and format attributes. The following code generates a file called TOC_page_2.PNG from the second page of myBook.pdf:
destination="images"> |
The following code generates thumbnails from a range of pages and changes the image background to transparent (the default is opaque):
destination="\myBook\subset" imagePrefix="abridged"> |
For an example of how to generate thumbnail images and link them to pages in the source PDF document, see the cfpdf tag in the CFML Reference.
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. |
Using the Duplicate function to create versions of a PDF document
You can use the Duplicate function to clone PDF variables, which is an efficient way to create different versions of a PDF document from a single source file. For example, you can customize PDF output based on your audience by creating clones of a PDF variable and performing different actions on each clone. The following example shows how to create a clone of a PDF document in memory, and create one version of the document with a watermark and another version of the document where permissions are restricted:
<!--- This code reads a PDF document into a PDF variable called pdfVar1. |
