<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, cfdocument, cfhtmltopdfitem ,cfdocumentitem
Syntax
<cfhtmltopdf> encryption = "AES_128|RC4_40|RC4_128|RC4_128M|None" </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. |
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 |
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.
Limitation: If you use cfhtmltopdf to convert an HTML page, that contains a form, to PDF, the resultant PDF will not contain the form fields. This is a limitation of the PDFg service, if PDFg is configured to run as a service. If you run PDFg from the command line, then the form fields will work as expected.
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" />
More like this
Sign in to your account