cfprint

Description

Prints specified pages from a PDF file. Use this tag to perform automated batch print jobs. Use the cfprint tag to print any PDF document, including the ones generated by the cfdocument, cfpdf, and cfpdfform tag. Also, you use this tag to print Report Builder reports exported in PDF format.

History

ColdFusion 8: Added this tag.

Syntax

<cfprint 
    source = "absolute or relative pathname to a PDF file|PDF document variable" 
    attributeStruct = "ColdFusion structure that contains standard print request 
        key-value pairs" 
    color = "yes|no" 
    copies = "number of copies" 
    fidelity = "yes|no" 
    pages = "page or pages to print" 
    password = "PDF source file owner or user password" 
    paper = "letter|legal|A4|A5|B4|B5|B4-JIS|B5-JIS|any media supported by the printer" 
    printer = "string that specifies the printer name" 
    type = "PDF">

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.

Attributes

Attribute	Description	Required	Default
attributeStruct	ColdFusion structure used to specify additional print instructions. Individually named attributes take precedence over the key-value pairs in the attribute structure. For information about key-value pairs, see the table in the section attributeStruct.	Optional
color	Color or monochrome printing: yes: print in color no: print in black and white, with colors in shades of gray	Optional
copies	Number of copies to print. The value must be greater than or equal to 1.	Optional
fidelity	Whether to print a job based on the print requirements specified. Valid values are: yes: if the job cannot be printed exactly as specified in the print requirements, the job is rejected. no: a reasonable attempt to print the job is acceptable	Optional	no
pages	Pages in the source file to print. Duplicate pages and pages beyond the total count of pages in the document are ignored as long as there is at least one page between 1 and the total number of pages in the document. You can combine individual page numbers and page ranges, for example, 1–3,6,10–20. If you do not specify a value for the pages attribute, ColdFusion prints the entire document.	Optional	all
paper	Paper used for the print job. The value can be any returned by the GetPrinterInfo function. The following values are valid: na-letter na-legal iso-a4 iso-a5 iso-b4 iso-b5 jis-b4 jis-b5 For more information, see the section Supported paper types.	Optional
password	The owner or user password for the PDF source file. If the PDF file is password-protected, specify this attribute for the file to print.	Optional
printer	The name of a printer. An example in Windows is \\s1001prn02\NTN-2W-HP_BW02. The default name is the default printer for the account where the ColdFusion server is running. Printer names are case sensitive and must be entered exactly as they appear in the System Information page of the ColdFusion Administrator. For more information, see Usage.	Optional
source	Source document to print. Specify one of the following: An absolute or relative pathname to an on-disk or in-memory PDF document file, for example, c:\work\myPDF.pdf or myPDF.pdf. The default directory is the template directory. A PDF document variable in memory that is generated by the cfdocument tag or the cfpdf tag, for example, "myPDFdoc".	Required
type	The file type of the document being printed. The only valid value is PDF.	Optional	PDF

Usage

Use the cfprint tag for automated batch printing of PDF documents. For example, you can run a batch job each evening that generates a report in PDF format and then prints either the entire report or selected pages for review the next morning without user intervention.
Most of the cfprint tag attributes are printer-dependent. If a printer does not support a specified attribute, it ignores the instruction. The default settings for the attributes also are printer-dependent. If you set a default printer, only specify the PDF file source and the password, if the file is password-protected.
Note: The particular printer attributes supported are dependent on the operating system, the network printer server, if there is one, and the printer. The cfprint tag is dependent on the Java Print Service (JPS). Many printers support attributes that are not accessible from JPS. For example, the JPS for a Macintosh OSX running JDK 1.5 supports the fewest printer attributes. Upgrading to JDK 1.6 adds some functionality, but finishing attributes are still not supported.
If the fidelity attribute is set to yes, the job does not print if any of the specified attributes are not supported by the printer. If the fidelity attribute is set to no, the printer accepts the print job and either ignores any attribute it does not support or substitutes a reasonable alternative for the attribute.
To determine which attributes are supported on a specified printer, use the GetPrinterInfo function.

Example

The following example shows how to use the attributeStruct attribute and the cfprint tag to print five, double-sided copies of a letter-sized PDF document, which are stapled on the top-left corner and collated:

<cfset aset=StructNew()> 
<cfset aset["sides"] = "duplex"> 
<cfprint type="pdf" source="myfile.pdf"  
    printer="\\s1001prn02\NTN-2W-HP_BW02" copies="5" paper="letter"  
    attributeStruct="#aset#">

The following example shows how to specify all of the print attributes with the attributeStruct attribute:

<cfset aset=StructNew()> 
<cfset aset["paper"] = "letter"> 
<cfset aset["sides"] = "duplex"> 
<cfset aset["copies"] = "5"> 
<cfset aset["printer"] = "\\s1001prn02\NTN-2W-HP_BW02"> 
 
<cfprint type="pdf" source="myfile.pdf" attributeStruct="#aset#">

Printers have a setting called autoRotateAndCenter, which is set to yes by default. The following example shows how to override the default autoRotatateAndCenter setting and use the orientation setting instead:

<cfset aset=StructNew()> 
    <cfset aset["autoRotateAndCenter"] = "no"> 
    <cfset aset["orientation"] = "portrait"> 
     
    <cfprint printer="myprinter" source="_mydoc.pdf" attributeStruct="#aset#">

To run a print job asynchronously, start a print job in a thread. Do not wait for the print job to be sent to the printer before proceeding. To start a print job in a thread, enclose the cfprint tag within cfthread start and end tags, as the following example shows:

<cfthread name="mythread" action="run"> 
    <cfprint type="pdf" source="myfile.pdf" printer="\\s1001prn02\NTN-2W-HP_BW02"> 
</cfthread> 
....

For more information, see cfthread.

cfmldocs