<cfhtmltopdf> creates high quality PDF output from a text block containing CFML and HTML using the PDF Service Manager.

The WebKit implementation for <cfhtmltopdf> is referred as PDFG (acronym of PDF Generator) which is shipped as part of the Jetty installer. The component running inside the Jetty  server is referred as the service manager, which takes request for PDF conversion from one or many ColdFusion server/s. (In Windows, the service runs as the ColdFusion 11 Add-on service, which processes both Solr and PDFG requests.)

The WebKit implementation for <cfhtmltopdf>:

  • Encapsulates the PDF conversion library.
  • Performs HTML to PDF conversion in process.

When you generate a PDF using HTML or CFML, you have to ensure that XSS vulnerabilities cannot be exploited. Hence, you must take relevant measures to protect your system against such vulnerabilities. Also, note that ColdFusion provides encoding functions for XSS protection. See the following functions:

Category

Data output tags

History

ColdFusion (2016 release) Update 3 - Added the attribute language.

See Also

cfhtmltopdfitem

Syntax

<cfhtmltopdf>

encryption = "AES_128|RC4_40|RC4_128|RC4_128M|None"
source = "URL|pathname absolute or relative to web root"
destination = "filename"
language="language name"
marginBottom = "number"
marginLeft = "number"
marginRight = "number"
marginTop = "number"
name = "output variable name"
orientation = "portrait|landscape"
overwrite = "yes|no"
ownerPassword = "password"
pageHeight = "page height in inches(default)"
pageType = "page type"
pageWidth = "page width in inches(default)"
permissions = "permission list"
saveAsName = "PDF filename"
unit = "in|cm"
userPassword = "password"

HTML and CFML code

</cfhtmltopdf>

Attributes

Attribute

Req/Opt

Default

Description

encryption

Optional

none

 AES_128

 RC4_40

 RC4_128

 RC4_128M

 None

source

Required

 

URL of the source HTML document. In ColdFusion 11, an HTTP URL auto-redirects to an HTTPS URL. In ColdFusion 2016, enter the HTTPS URL manually as there will be no auto-redirects from HTTP to HTTPS.

destination

Optional

 

Pathname of a file to contain the PDF output. If you omit the destination attribute, ColdFusion displays the output in the browser.

language

Optional

English

Document language.

marginBottom

Optional

 

Bottom margin in inches (default) or centimeters. To specify the bottom margin in centimeters, include the unit=cm attribute.

marginLeft

Optional

 

Left margin in inches (default) or centimeters. To specify the left margin in centimeters, include the unit=cm attribute.

marginRight

Optional

 

Right margin in inches (default) or centimeters. To specify the right margin in centimeters, include the unit=cm attribute.

marginTop

Optional

 

Top margin in inches (default) or centimeters. To specify the top margin in centimeters, include the unit=cm attribute.

name

Optional

 

Name of an existing variable into which the tag stores the PDF.

orientation

Optional

portrait

Page orientation:

portrait

landscape

overwrite

Optional

no

Specifies whether ColdFusion overwrites an existing file. Used in conjunction with the destination attribute.

ownerPassword

Optional

 

Specifies the owner password. Cannot be same as userPassword.

pageHeight

Optional

 

Page height in inches (default) or centimeters. This attribute is only valid if pagetype=custom. To specify page height in centimeters, include the unit=cm attribute.

pageType

Optional

letter

Page type into which ColdFusion generates the report:

 

legal: 8.5 inches x 14 inches.

letter: 8.5 inches x 11 inches.

A4: 8.27 inches x 11.69 inches.

A5: 5.81 inches x 8.25 inches.

B4: 9.88 inches x 13.88 inches.

B5: 7 inches x 9.88 inches.

B4-JIS: 10.13 inches x 14.31 inches.

B5-JIS: 7.19 inches x 10.13 inches.

custom: custom height and width.

If you specify custom, also specify the pageHeight and pageWidth attributes, can optionally specify margin attributes and whether the units are inches or centimeters.

pageWidth

Optional

 

Page width in inches (default) or centimeters. This attribute is only valid if pageType=custom. To specify page width in centimeters, include the unit=cm attribute.

permissions

Optional

 

(format="PDF" only) Sets one or more of the following permissions:

AllowPrinting

AllowModifyContents

AllowCopy

AllowModifyAnnotations

AllowFillIn

AllowScreenReaders

AllowAssembly

AllowDegradedPrinting

   AllowSecure

   All

   None

Separate multiple permissions with commas.

saveAsName

Optional

 

The filename that appears in the SaveAs dialog when a user saves a PDF file written to the browser.

unit

Optional

in

Default unit for the pageHeight, pageWidth, and margin attributes:

in: inches.

cm: centimeters.

userPassword

Optional

 

Specifies a user password. Cannot be same as ownerPassword.

Note: <cfhtmltopdfItem> is added to support adding header/footer/pagebreak in the generated PDF.  See The new <cfhtmltopdfitem> tag.

Refer to the kb doc Differences between cfdocument and cfhtmltopdf for more information.

Examples

The following example shows the most basic usage of <cfhtmltopdf>, to create a PDF from CFML code, returning a PDF for display:

<cfhtmltopdf>
This is a test <cfoutput>#now()#</cfoutput>
</cfhtmltopdf>

The following example shows the most basic usage of <cfhtmltopdf>, to create a PDF from content returned from a URL, returning a PDF for display:

<cfhtmltopdf source="http://www.google.com/" />

The following example shows using options to control height, width, and save the content to a file instead of for display. The file is saved (by default) into the same directory as the template containing the code:

<cfhtmltopdf
  destination="usage_example.pdf" overwrite="yes"
  source="http://www.google.com/"
  unit="in" pageheight="8" pagewidth="4"
  pagetype="custom" />

The following example shows how you can set margins, and also adds code to display the resulting file to the user using CFContent:

<cfhtmltopdf destination="usage_example2.pdf"
  source="http://www.google.com" overwrite="true"  
  orientation="portrait"  pagetype="A4" margintop="1" marginbottom="1" 
  marginleft="1" marginright="1" />
 
<cfcontent file="#getdirectoryfrompath(getbasetemplatepath())#usage_example2.pdf" type="application/pdf" >

The following example shows how you can protect the PDF, requiring the user to enter a password to open the file:

<cfhtmltopdf destination="usage_example3.pdf " 
  source="http://www.google.com" overwrite="true"
  orientation="portrait"  pagetype="A4" margintop="1" marginbottom="1"
  marginleft="1" marginright="1" ownerpassword="owner" userpassword="user"
  encryption="RC4_128" permissions="AllowPrinting,AllowCopy" />

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy