Using cfdocument

Using <cfdocument>

<cfdocument> is one of a family of three tags supports all sorts of attributes for sophisticated printed output control. An understanding of these tags and attributes, as well as the scope and limitations of this functionality, is important.

What Is Supported by <cfdocument>?

The <cfdocument> tag supports all of the following:

• HTML 4

• XML 1

• DOM level 1 and 2

• CSS1 and CSS2

Some elements, however, are not supported:

• JavaScript and DHTML is not supported by <cfdocument>. As such, page elements that are rendered programmatically will not be rendered in the generated printable output.

• Plug-ins are not supported, and so embedded Flash, ActiveX, applets, etc., will not be printed.

TIP

<a href> tags are supported, and links within the generated PDF and SWF output will work correctly.

<cfdocument> should thus be more than able to convert all sorts of pages into printable PDF or FlashPaper.

Greater Output Control

<cfdocument> supports a whole series of attributes to give you greater control over printed output. Table 18.1 lists the supported attributes.

Table 18.1. <cfdocument> Attributes

ATTRIBUTE	DESCRIPTION
backgroundvisible	Whether or not to display page background, default is no.
encryption	Optional encryption, 128-bit or 40-bit (used by PDF only).
filename	Optional file name, if specified document is saved to disk instead of being served in the browser.
fontembed	Whether or not to embed used fonts, yes, no, or selective (default).
format	pdf or flashpaper, this attribute is required.
marginbottom	Page bottom margin, use unit to specify unit of measure.
marginleft	Page left margin, use unit to specify unit of measure.
marginright	Page right margin, use unit to specify unit of measure.
margintop	Page top margin, use unit to specify unit of measure.
name	Optional variable name to contain generated output.
orientation	Page orientation, portrait (the default) or landscape.
overwrite	Whether or not to overwrite existing documents (if using filename).
ownerpassword	Optional owner password (used by PDF only).
pageheight	Page height (used if pagetype="custom"), use unit to specify unit of measure.
pagetype	Page size, supports legal, letter, A4, A5, B5, and custom.
pagewidth	Page width (used if pagetype="custom"), use unit to specify unit of measure.
scale	Scaling factor, default is calculated by ColdFusion automatically.
unit	Unit of measure, in (inches) or cm (centimeters).
userpassword	Optional user password (used by PDF only).

Saving Generated Output

<cfdocument> embeds generated output in your Web page. You may opt to save the generated files to disk instead of serving them in real-time. Reasons to do this include:

• Caching, so as to not have to regenerate pages unnecessarily

• E-mailing generated content

• Generating pages that may be served statically

To save generated output simple provide a filename in the filename attribute. The specified file name must be fully qualified (with a complete path). Here is a simple example:

 <cfset filePath=ExpandFile("output.swf")> <cfdocument format="flashpaper"             filename="#filePath#"             overwrite="true"> Hello world! </cfdocument> 

NOTE

If overwrite="false" (the default), and the destination file already exists, an exception will be thrown.

TIP

Use the ExpandPath() function to convert file names to fully qualified paths.