|
cfprint
DescriptionPrints
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.
HistoryColdFusion
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
|
Req/Opt
|
Default
|
Description
|
attributeStruct
|
Optional
|
|
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.
|
color
|
Optional
|
|
Color or monochrome printing:
|
copies
|
Optional
|
|
Number of copies to print. The value must
be greater than or equal to 1.
|
fidelity
|
Optional
|
no
|
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
|
pages
|
Optional
|
all
|
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.
|
paper
|
Optional
|
|
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.
|
password
|
Optional
|
|
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.
|
printer
|
Optional
|
|
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.
|
source
|
Required
|
|
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".
|
type
|
Optional
|
PDF
|
The file type of the document being printed.
The only valid value is PDF.
|
UsageUse 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.
Supported paper typesYou can use the equivalent page types supported
by the cfdocument tag, but they
are not returned by the GetPrinterInfo function:
cfdocument
|
cfprint
|
letter
legal
A4
A5
B4
B5
B4-JIS
B5-JIS
|
na-letter
na-legal
iso-a4
iso-a5
iso-b4
iso-b5
jis-b4
jis-b5
|
View a list of configured printersLog on to the ColdFusion
Administrator.
Click the System Information icon located at the top right
of the Administrator Console window. (The icon has an “i” on it.)
Scroll to the bottom of the System Information page. Under
Printer Details is the Default Printer. Below the default printer
is Printers, which lists the configured printers available to ColdFusion,
including the default printer.
Printer configuration
is operating system-dependent. Configure printers outside of ColdFusion.
View the print logLog on to the ColdFusion Administrator.
Expand the Debugging and Logging topic.
Click the Log Files link. The print.log file appears in the
list of log files.
Permissions for printingIf the PDF file is encrypted, the permissions
for the file must be set to AllowPrinting, or specify
the owner password to print the file. Use the protect action
of the cfpdf tag to set permissions and passwords
on PDF files. For more information, see Permissions for PDF documents
in cfpdf.
If
a Security Manager is installed, the following permission is required
in the coldfusion.policy file to initiate a print job request:
grant { permission java.lang.RuntimePermission "queuePrintJob"; };
In
Windows systems, the account running the ColdFusion server must
have PRINTER_ACCESS_USE access rights for each
printer it uses. Even if the printer is configured locally on the
system, the printer is not available if the account in which ColdFusion
is running does not have the proper permissions.
Note: By
default, ColdFusion installs and runs as the Local System account,
which may not have printer queue access rights. For information
on running ColdFusion as a specific user, see the following Tech
Note: http://www.adobe.com/cfusion/knowledgebase/index.cfm?id=tn_17279
attributeStructThe
following table lists the optional attributeStruct key-value
pairs that you use to specify print requests:
Element
|
Description
|
autoRotateAndCenter
|
Adjusts the document's orientation to match
the orientation specified in the printer attributes and centers the
page in the imaging area:
yes:
the orientation, if specified, is ignored (default)
no: the orientation, if specified, is applied
to the document
|
collate or sheetCollate
|
Specifies whether the sheets of each copy
of each printed document in a job are in sequence when multiple copies
of the document are specified by the copies attribute:
|
color or chromaticity
|
Specifies color or monochrome printing.
Monochrome printing displays colors in shades of gray:
yes: print in color.
no: print in monochrome.
|
copies
|
Number of copies of the source document
to print. Valid values are integers greater than or equal to 1.
|
coverPage or jobSheets
|
Specifies which job start and end sheets,
if any, are printed with a job:
|
fidelity
|
Specifies whether to print a job based on
the print requirements specified. The following values are valid
values:
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 (default).
|
finishings
|
Finishing operation to perform after each
copy of a document is printed:
staple-top-left
staple-bottom-left
staple-top-right
staple-bottom-right
edge-stitch-left
edge-stitch-right
edge-stitch-top
edge-stitch-bottom
dual-right
dual-top
dual-bottom
dual-left
|
jobHoldUntil
|
Date-time attribute for the exact date and
time at which the job is available for printing. Valid values are ColdFusion
date and time variables.
|
jobName
|
The name of a print job.
|
jobPriority
|
Integer value that represents a print job's
priority. Among those jobs that are ready to print, a printer must print
all jobs with a priority value of n before printing those
with a priority value of n-1 for all n. Valid values are
integers from 1 (lowest priority) through 100 (highest priority).
|
numberUp
|
Number of pages to print on a single side
of paper. The value must be a number greater than or equal to 1.
|
orientation or orientationRequested
|
Orientation of the page to be printed. The
only valid value for PDF documents is portrait.
To change the orientation to landscape, set the autoRotateAndCenter to yes (which
is the default value). The autoRotateAndCenter instruction
overrides the orientation instruction.
|
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.
|
pageScaling
|
Specifies how pages are scaled on the paper:
fit-to-printer-margins: Reduces or enlarges
each page to fit the printable area of the currently selected paper
size.
reduce-to-printer-margins: Shrinks large
pages to fit the currently selected paper size but does not enlarge
small pages. If an area is selected and is larger than the printable
area of the currently selected paper, the page is scaled to fit
the printable area (Default).
none: Prints the upper left or center of
a page (if autorotated and centered) without scaling. Pages that don’t
fit on the paper are cropped.
|
pageSubset
|
Prints a subset of pages in specified by
the pages attribute:
all: Prints
all the pages in the specified page range (Default).
odd: Prints only the odd pages in the specified
page range.
even: Prints only the even pages in the
specified page range.
|
paper
|
Paper used for the print job. The value
can be any returned by the GetPrinterInfo function.
The following values are the most common:
|
presentationDirection
|
Used in conjunction with the numberUp attribute
to indicate the layout of multiple document pages on one side of
the paper.
|
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 you must enter the names exactly
as they appear in the System Information page of the ColdFusion
Administrator. For more information on viewing print logs, see Usage.
|
quality
|
Print quality for the print job:
|
requestingUserName
|
A string that specifies the name of the
end user that submitted the print job.
|
reversePages
|
Prints pages in reverse order. If page ranges
are entered, the pages print opposite of the order in which they were
entered. For example, if the Pages box shows 3-5, 7-10, selecting
Reverse Pages prints pages 10-7, and then 5-3.
|
sides
|
Sides of the paper on which the pages are
printed:
|
usePdfPageSize
|
Uses the PDF page size to determine the
area of the paper printed rather than the paper size. This is useful for
printing PDF documents that contain multiple page sizes:
|
ExampleThe
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.
|