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

See also

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

History

ColdFusion 9: Add ppt support to the srcFile 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

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 filename attribute 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 Optimizing transient 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 cfdocument tag.

Supported CSS styles

The cfdocument tag supports the following CSS styles:

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

• totalsectionpagecount

• currentsectionpagenumber

ColdFusion 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" 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 totalsectionpagecount variable 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

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