cfdocument

Go to ColdFusion CFML Reference User Guide

Last updated on | Also Applies to ColdFusion

FORMAT="flashpaper" HAS BEEN DEPRECATED

For a full list of deprecated features, refer to Deprecated features.

Description

Creates PDF or FlashPaper output from a text block containing CFML and HTML.

Syntax

<cfdocument 
format = "PDF|FlashPaper" 
authPassword = "authentication password" 
authUser = "authentication user name" 
backgroundVisible = "yes|no" 
bookmark = "yes|no" 
encryption = "128-bit|40-bit|none" 
filename = "filename" 
fontEmbed = "yes|no" 
formfields = "yes|no" 
formsType = "FDF|PDF|HTML|XML" 
localUrl = "yes|no" 
marginBottom = "number" 
marginLeft = "number" 
marginRight = "number" 
marginTop = "number" 
mimeType = "text/plain|application/xml|image/jpeg|image/png|image/bmp|image/gif"
name = "output variable name" 
openpassword = "password to open protected documents" 
orientation = "portrait|landscape" 
overwrite = "yes|no" 
ownerPassword = "password" 
pageHeight = "page height in inches" 
pageType = "page type" 
pageWidth = "page width in inches" 
pdfa = "yes|no" 
permissions = "permission list" 
permissionspassword = "password to access restricted permissions" 
proxyHost = "IP address or server name for proxy host" 
proxyPassword = "password for the proxy host" 
proxyPort = "port of the proxy host" 
proxyUser = "user name for the proxy host" 
saveAsName = "PDF filename" 
scale = "percentage less than 100" 
src = "URL|pathname relative to web root" 
srcfile = "absolute pathname to a file" 
tagged = "yes|no" 
unit = "in|cm" 
userAgent = "HTTP user agent identifier" 
userPassword = "password"> 
HTML and CFML code 
</cfdocument>

Note: You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

History

ColdFusion 9: Add ppt support to the srcFile attribute. Added the following attributes to support conversion of a Word document to PDF or HTML using OpenOffice libraries:

formfields attribute
formsType attribute
openpassword attribute
permissionspassword attribute
pdfa attribute
tagged attribute

ColdFusion 8: Added the following attributes and variables:

bookmark attribute
localUrl attribute
Ability to embed existing PDF forms by using the cfpdfform tag in the cfdocument tag.
ColdFusion determines the MIME type of a source file based on the source filename, if the mimeType attribute is not specified.
Ability to pass a PDF variable created with the cfdocument tag as the source for the cfpdf tag.
authPassword, authUser, proxyHost, proxyPassword, proxyPort, proxyUser, and userAgent attributes
saveAsName attribute
totalsectionpagecount and currentsectionpagenumber scope variables.

ColdFusion MX 7.01: Added the src, srcfile, and mimetype attributes.ColdFusion MX 7: Added this tag.

Attributes

Attribute	Req/Opt	Default	Description
authPassword	Optional		Password sent to the target URL for Basic Authentication. Combined with username to form a base64 encoded string that is passed in the Authenticate header. Does not provide support for Integrated Windows, NTLM, or Kerebos authentication.
authUser	Optional		User name sent to the target URL for Basic Authentication. Combined with password to form a base64 encoded string that is passed in the Authenticate header. Does not provide support for Integrated Windows, NTLM, or Kerebos authentication.
backgroundVisible	Optional	no	Specifies whether the background prints when the user prints the document: yes: includes the background when printing. no: does not includes the background when printing.
bookmark	Optional	no	Specifies whether bookmarks are created in the document: yes: creates bookmarks. no: does not create bookmarks.
encryption	Optional	none	(format="PDF" only) Specifies whether the output is encrypted: 128-bit 40-bit none
filename	Optional		Pathname of a file to contain the PDF or FlashPaper output. If you omit the filename attribute, ColdFusion displays the output in the browser.
fontEmbed	Optional	yes	Specifies whether ColdFusion embeds fonts in the output: yes: embeds fonts. no: does not embed fonts. selective: embed sall fonts except Java fonts and core fonts.
format	Required		Report format: PDF FlashPaper
formfields	Optional	yes	This attribute is available only if you have integrated OpenOffice with ColdFusion.A Boolean value that specifies if form fields are exported as widgets or only their fixed print representation is exported.
formstype	Optional	FDF	This attribute is available only if you have integrated OpenOffice with ColdFusion.Specifies the submitted format of a PDF form. It can be one of the following values: FDF PDF HTML XML
localUrl	Optional	no	Specifies whether to retrieve image files directly from the local drive: yes: ColdFusion retrieves image files directly from the local drive rather than by using HTTP, HTTPS, or proxy. no: ColdFusion uses HTTP, HTTPS, or proxy to retrieve image files even if the files are stored locally. For more information, see the "Using an image file URL" section.
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.
mimeType	Optional	text/ html	MIME type of the source document. Supported MIME types are: text/ html text/plain application/ xml image/ bmp image/jpeg image/png image/gif If you do not specify this attribute explicitly, ColdFusion uses the filename to determine the MIME type.
name	Optional		Name of an existing variable into which the tag stores the PDF or FlashPaper output.
openpassword	Optional		This attribute is available only if you have integrated OpenOffice with ColdFusion.Password required to open a password-protected document.
orientation	Optional	portrait	Page orientation: portrait landscape
overwrite	Optional	no	Specifies whether ColdFusion overwrites an existing file. Used in conjunction with the filename attribute.
ownerPassword	Optional		(format="PDF" only) 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.
pdfa	Optional	no	This attribute is available only if you have integrated OpenOffice with ColdFusion.A Boolean value that specifies if you need to create a PDF of type PDF/A-1 (ISO 19005-1:2005 ) .
permissionpasswrd	Optional		This attribute is available only if you have integrated OpenOffice with ColdFusion.Password required to access restricted permissions. The restricted permissions are specified using the permissions attribute.
permissions	Optional		(format="PDF" only) Sets one or more of the following permissions: AllowPrinting AllowModifyContents AllowCopy AllowModifyAnnotations AllowFillIn AllowScreenReaders AllowAssembly AllowDegradedPrinting Separate multiple permissions with commas.
proxyHost	Optional		Host name or IP address of a proxy server to which to send the request.
proxyPassword	Optional		Password required by the proxy server.
proxyPort	Optional	80	The port to connect to on the proxy server.
proxyUser	Optional		User name to provide to the proxy server.
scale	Optional	Calculated by ColdFusion	Scale factor as a percentage. Use this option to reduce the size of the HTML output so that it fits on that paper. Specify a number less than 100.
saveAsName	Optional		(format="PDF" only) The filename that appears in the SaveAs dialog when a user saves a PDF file written to the browser.
src	Optional		URL or the relative path to the web root. You cannot specify both the src and srcfile attributes. The file must be in a browser-writable format such as, HTML, HTM, BMP, PNG, and so on.
srcfile	Optional		Absolute path of a file that is on the server. You cannot specify both the src and srcfile attributes. The file must be a PPT file, a Word file, or be in a browser-writable format such as, HTML, HTM, BMP, PNG, and so on.
tagged	Optional	no	This attribute is available only if you have integrated OpenOffice with ColdFusion.A Boolean value that determines if the PDF is created using the Tagged PDF tag.
unit	Optional	in	Default unit for the pageHeight, pageWidth , and margin attributes: in: inches. cm: centimeters.
userAgent	Optional	ColdFusion	Text to put in the HTTP User-Agent request header field. Used to identify the request client software.
userPassword	Optional		(format="PDF" only) Specifies a user password.Cannot be same as ownerPassword .

Usage

Use the cfdocument tag to render HTML and CFML output into PDF or FlashPaper format. ColdFusion does not return HTML and CFML outside of the <cfdocument> </cfdocument> pair.
The cfdocument tag can render HTML that supports the following standards:

HTML 4.01
XML 1.0
DOM Level 1 and 2
CSS1 and CSS2 (For more information, see the "Supported CSS styles" section).
The cfdocument tag does not support the Internet Explorer-specific HTML generated by Microsoft Word.Use the following syntax in the filenameattribute to specify an in-memory file, which is not written to disk. In-memory files speed processing of transient data.

ram:///filepath

The filepath can include directories, for example ram:///petStore/tracking/ordersummary.pdf. Create the directories in the path before you specify the file. For more information on using in-memory files, see Working with in-memory files in the Developing ColdFusion Applications.
You can use the src, srcfile , and mimeType attributes to create PDF or FlashPaper output from a specified file or URL. Use the src and srcfile attributes instead of using the cfhttp tag to display the result in the cfdocument tag. When you specify the src or srcfile attributes, do not include any other content inside the cfdocument tag: ColdFusion ignores the additional content. The PDF or FlashPaper document returned by the cfdocument tag overwrites any previous HTML in the input stream and ignores any HTML after the </cfdocument> tag.
You cannot embed a cfreport tag in a cfdocumenttag .

Note: If you notice that the header text is cropped in the cfdocument tag output, increase the value of the marginTop attribute.

Note: The cfdocument will not work as expected if the input statement is type="file". For example,

<input class="entryx" id="Photo" name="Photo" onkeypress="return noEnter(event)" size="40" type="file" value="" />

As a work-around, run the PDFg service from the command line.

Supported CSS styles

The cfdocument tag supports the following CSS styles:

background	background-attachment	background-color	background-image
background-position	background-repeat	border	border-bottom
border-bottom-color	border-bottom-style (solid border only)	border-bottom-width	border-color
border-left	border-left-color	border-left-style (solid border only)	border-left-width
border-right	border-right-color	border-right-style (solid border only)	border-right-width
border-spacing	border-style (solid border only)	border-top	border-top-color
border-top-style (solid border only)	border-top-width	border-width	bottom
clear	clip	color	content (strings, counters only)
counter-increment	counter-reset	cursor	display
float	font	font-family	font-size
font-style	font-weight	height	left
line-height	line-style-type	margin
margin-bottom	margin-left	margin-right	margin-top
outline	outline-color	outline-style (solid, dotted, dashed only)	outline-width
padding	padding-bottom	padding-left	padding-right
padding-top	page-break-after	page-break-before	page-break-inside
position	right	text-align (left, right, and center)	text-decoration
text-indent	top	unicode-bidi	vertical-align
visibility	white space (normal, nowrap only)	width	z-index

Using an image file URL

For optimal performance and reliability, Adobe recommends that you specify a local file URL for images stored on the server. In the following example, the cfdocument tag requests the server for images over HTTP even though the image files are stored locally:

<cfdocument format="PDF"> 
<table> 
<tr> 
<td>bird</td> 
<td><img src="images/bird.jpg"></td> 
</tr> 
<tr> 
<td>fruit</td> 
<td><img src="images/fruit.jpg"></td> 
</tr> 
<tr> 
<td>rose</td> 
<td><img src="images/rose.jpg"></td> 
</tr> 
</table> 
</cfdocument>

Also, in some applications, the browser displays a Red X image error instead of the image in the browser. For better performance, and to avoid Red X image errors, set the localUrl attribute to yes:

<cfdocument localUrl="yes" format="PDF"> 
<table> 
<tr> 
<td>bird</td> 
<td><img src="images/bird.jpg"></td> 
</tr> 
<tr> 
<td>fruit</td> 
<td><img src="images/fruit.jpg"></td> 
</tr> 
<tr> 
<td>rose</td> 
<td><img src="images/rose.jpg"></td> 
</tr> 
</table> 
</cfdocument>

Scope variables

When you use the cfdocument tag, ColdFusion creates a scope named cfdocument. This scope contains the following variables:

currentpagenumber
totalpagecount
totalsectionpagecount
currentsectionpagenumber
ColdFusion lets you use the scope variables inside any expression within a cfdocumentitem tag. For example, you can use the currentpagenumbervariable to place the section name on even pages and the chapter name on odd pages in the header, as follows:

<cfdocument format="flashpaper"> 
<cfdocumentitem type="header" evalAtPrint="true"> 
<cfif (cfdocument.currentpagenumber mod 2) is 0> 
<cfoutput>#cfdocument.totalpagecount#</cfoutput> 
<cfelse> 
<cfoutput>#cfdocument.currentpagenumber#</cfoutput> 
</cfif> 
</cfdocumentitem> 
... 
</cfdocument>

If you define the cfdocumentsection tag within the cfdocument tag, then specify the totalsectionpagecountvariable as follows:

<cfdocument format="pdf"> 
<cfdocumentitem type="header" evalatprint="true" > 
<cfif (cfdocument.currentpagenumber mod 2) is 0> 
<cfoutput>#cfdocument.totalpagecount#</cfoutput> 
<cfelse> 
<cfoutput>#cfdocument.currentpagenumber#</cfoutput> 
</cfif> 
<cfoutput>cfdocument.currentpagenumber :#cfdocument.currentpagenumber#</cfoutput> 
<cfoutput>cfdocument.totalpagecount :#cfdocument.totalpagecount#</cfoutput> 
<cfoutput>cfdocument.totalsectionpagecount :#cfdocument.totalsectionpagecount#</cfoutput> 
<cfoutput>cfdocument.currentsectionpagenumber :#cfdocument.currentsectionpagenumber#</cfoutput> 
</cfdocumentitem> 

<cfdocumentitem type="footer" evalatprint="true" > 
<cfif ! (cfdocument.currentpagenumber mod 2) is 0> 
<cfoutput>if#cfdocument.totalpagecount#</cfoutput> 
<cfelse> 
<cfoutput>else#cfdocument.currentpagenumber#</cfoutput>
</cfif> 
</cfdocumentitem> 
<cfdocumentsection >Example Text 
</cfdocumentsection> 
</cfdocument>

Bookmarks

ColdFusion 9 supports bookmarks. In the cfdocument tag, set the bookmark attribute to yes. Then specify the bookmark name for each cfdocumentsection tag.
The following example shows how to specify bookmarks for document sections:

<!--- This example creates two bookmarks named "Section 1" and "Section 2" in a PDF file. ---> 
<cfdocument format="pdf" bookmark="yes"> 
<cfdocumentsection name="Section 1"> 
<!--- Insert HTML content here.---> 
</cfdocumentsection> 
<cfdocumentsection name="Section 2"> 
<!--- Insert HTML content here. ---> 
</cfdocumentsection> 
</cfdocument>

Example

<!--- The following example shows how to use the cfdocument scope variables to generate section numbers and page numbers. ---> 

<cfdocument format="pdf"> 
<cfdocumentitem type="header" evalatprint="true"> 
<table width="100%" border="0" cellpadding="0" cellspacing="0"> 
<tr><td align="right"><cfoutput>#cfdocument.currentsectionpagenumber# of 
#cfdocument.totalsectionpagecount#</cfoutput></td></tr> 
</table> 
</cfdocumentitem> 

<cfdocumentitem type="footer" evalatprint="true"> 
<table width="100%" border="0" cellpadding="0" cellspacing="0"> 
<tr><td align="center"><cfoutput>#cfdocument.currentpagenumber# of 
#cfdocument.totalpagecount#</cfoutput></td></tr> 
</table> 
</cfdocumentitem> 

<cfdocumentsection> 
<h1>Section 1</h1> 
<cfloop from=1 to=50 index="i"> 
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.<p> 
</cfloop> 
</cfdocumentsection> 

<cfdocumentsection> 
<h1>Section 2</h1> 
<cfloop from=1 to=50 index="i"> 
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.<p> 
</cfloop> 
</cfdocumentsection> 

<cfdocumentsection> 
<h1>Section 3</h1> 
<cfloop from=1 to=50 index="i"> 
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.<p> 
</cfloop> 
</cfdocumentsection> 
</cfdocument>

cfdocument

Description

Category

Syntax

See also