Adobe ColdFusion 8

cfdocument

Description

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

Category

Data output tags

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"
    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"
    orientation = "portrait|landscape"
    overwrite = "yes|no"
    ownerPassword = "password"
    pageHeight = "page height in inches"
    pageType = "page type"
    pageWidth = "page width in inches"
    permissions = "permission list"
    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"
    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.

See also

cfdocumentitem, cfdocumentsection, cfformUsage, cfpdf, cfpdfform, cfpresentation, cfprint, cfreport

History

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

 

Name 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

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 Using an image file URL.

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.

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.

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, you must 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

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 in a browser-writable format such as, HTML, HTM, BMP, PNG, and so on.

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.

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 Supported CSS styles).

The cfdocument tag does not support the Internet Explorer-specific HTML generated by Microsoft Word.

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 cfdocument tag.

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

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

letter-spacing

line-height

list-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

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><image src="images/bird.jpg"></td>
        </tr>
        <tr>
            <td>fruit</td>
            <td><image src="images/fruit.jpg"></td>
        </tr>
        <tr>
            <td>rose</td>
            <td><image 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><image src="images/bird.jpg"></td>
        </tr>
        <tr>
            <td>fruit</td>
            <td><image src="images/fruit.jpg"></td>
        </tr>
        <tr>
            <td>rose</td>
            <td><image 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
  • totalsectionnumber
  • currentsectionpagenumber

ColdFusion 8 lets you use the scope variables inside any expression within a cfdocumentitem tag. For example, you can use the currentpagenumber variable 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">
        <cfif (cfdocument.currentpagenumber mod 2) is 0>
             <cfoutput>#sectionTitle#</cfoutput>
        <cfelse>
             <cfoutput>#chapterTitle#</cfoutput>
        </cfif>
    </cfdocumentitem>
        ...
</cfdocument>

Bookmarks

ColdFusion 8 supports bookmarks. In the cfdocument tag, set the bookmark attribute to yes. Then do one of the following:

  • Specify the bookmark name for each cfdocumentsection tag.
  • Use the cfdocumentitem type = "bookmark".

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

Example 1

<!--- This example creates generates a FlashPaper document. --->
<cfdocument format="flashpaper">
<p>This is a document rendered by the cfdocument tag.</p>

<table width="50%" border="2" cellspacing="2" cellpadding="2">
<tr>
<td><strong>Name</strong></td>
<td><strong>Role</strong></td>
</tr>
<tr>
<td>Bill</td>
<td>Lead</td>
</tr>
<tr>
<td>Susan</td>
<td>Principal Writer</td>
</tr>
<tr>
<td>Adelaide</td>
<td>Part Time Senior Writer</td>
</tr>
<tr>
<td>Thomas</td>
<td>Full Time for 6 months</td>
</tr>
<tr>
<td>Michael</td>
<td>Full Time for 4 months</td>
</tr>
</table>
</cfdocument>

Example 2

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

<cfdocument format="pdf">
<cfdocumentitem type="header">
    <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">
    <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>