|
cfreport
DescriptionUsed
to do either of the following:
Execute a report created
with the ColdFusion Report Builder, displaying it in PDF, Adobe® FlashPaper®, RTF,
HTML, XML or Excel format. Optionally, you can save this report
to a file.
Run a predefined Crystal Reports report. Applies only to
Windows systems.
SyntaxColdFusion Report Builder syntax:
<cfreport
format = "PDF|FlashPaper|Excel|RTF|HTML|XML"
template = "absolute pathname or pathname relative to the report file"
encryption = "128-bit|40-bit|none"
filename = "output filename"
name = "ColdFusion variable"
ownerpassword = "password"
overwrite = "no|yes"
permissions = "permission list"
query = "query variable"
resourceTimespan = #CreateTimeSpan (days, hours, minutes, seconds)#
style = "CSS style definition or css file pathname"
userpassword = "password">
<cfreportparam ...>
</cfreport>
Crystal Reports syntax:
<cfreport
report = "report path"
dataSource = "data source name"
formula = "formula"
orderBy = "result order"
password = "password"
timeout = "number of seconds"
type = "standard|netscape|microsoft"
username = "username">
</cfreport>
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.
HistoryColdFusion
8: Added the style and resourceTimespan attributes.
Added the HTML and XML values
to the format attribute.
ColdFusion MX 7.0.1:
Added the RTF value to the format attribute,
to let you generate reports in RTF format.
ColdFusion MX 7:
Added support for the ColdFusion Report Builder.
ColdFusion
MX: Changed data source connection behavior: Crystal Reports now establishes
an independent connection to the data source. The connection is
not subject to any ColdFusion data source-specific restrictions.
For example, the Crystal Reports server can access a data source,
regardless of whether it is disabled in the ColdFusion Administrator.
Attributes
Attribute
|
Applies to
|
Req/Opt
|
Default
|
Description
|
datasource
|
Crystal Reports
|
Optional
|
|
Name of registered or native data source.
|
encryption
|
Report Builder
|
Optional
|
none
|
(format="PDF" only) Type
of encryption for the report output. Valid values are:
|
filename
|
Report Builder
|
Optional
|
|
Filename to contain the report. You cannot
specify both the name and filename attributes.
The filename extension must match the value of the format attribute.
If
you write report output to an HTML file, ColdFusion automatically
creates a directory relative to the output file in the format filename_files.
Also, it generates PNG files for any charts in the report and copies
of any image files imported into the report and stores them in this
directory.
|
format
|
Report Builder
|
Required
|
|
Format of the report output:
PDF
FlashPaper
Excel
RTF
XML
HTML
When you write
report output directly to the browser in HTML format, ColdFusion
generates a temporary directory and files for the images in the
report. The location of the temporary directory that contains the
image files is:
C:\ColdFusion9\tmpCache\CFFileServlet\_cfreport\_report[unique_identifier]
To
determine when the images are removed from the browser, use the resourceTimespan attribute.
|
formula
|
Crystal Reports
|
Optional
|
|
One or more named formulas. Terminate each
formula with a semicolon. Use the format:
formula = "formulaname1 = 'formula1';formulaname2 = 'formula2';"
If
you use a semicolon in a formula, escape it by typing it twice (;;).
For example:
formula = "Name1 = 'Val_1a;;Val_1b';Name2 = 'Val2';"
|
name
|
Report Builder
|
Optional
|
|
Name of the ColdFusion variable that contains
the report output. You cannot specify both name and filename.
This attribute is not valid when format="HTML".
|
orderBy
|
Crystal Reports
|
Optional
|
|
Orders results according to your specifications.
|
overwrite
|
Report Builder
|
Optional
|
no
|
Specifies whether to overwrite files that
have the same name as that specified in the filename attribute:
|
ownerPassword
|
Report Builder
|
Optional
|
|
(format="PDF" only) Owner
password for the report,
|
password
|
Crystal Reports
|
Optional
|
|
Password that corresponds to username required
for database access. Overrides default settings for data source
in the ColdFusion Administrator.
|
permissions
|
Report Builder
|
Optional
|
|
(format="PDF" only) Specifies
one or more of the following permissions:
AllowPrinting
AllowModifyContents
AllowCopy
AllowModifyAnnotations
AllowFillIn
AllowScreenReaders
AllowAssembly
AllowDegradedPrinting
Separate
multiple permissions with commas.
|
query
|
Report
Builder
|
Optional
|
|
Name of the query that contains input data
for the report. This query overrides the query in the Report Builder
report. The ColdFusion query must contain at least all of the columns
included in the Report Builder query; however, the WHERE clause
can differ. If you omit this parameter, Report Builder uses the
data from the internal SQL statement or from cfreportparam items.
|
report
|
Crystal Reports
|
Required
|
|
Report pathname. Store Crystal Reports files
in the same directories as ColdFusion page files.
|
resourceTimespan
|
Report Builder
|
Optional
|
5 minutes
|
(format="HTML" only) Life
span of the resource directory. When you export a Report Builder
report in HTML format, ColdFusion writes any images or other resource
files in the report to a temporary resource directory. Use this
attribute to determine when the resource directory is deleted. For
the value, use the CreateTimeSpan function and
specify the time span in days, hours, minutes, and seconds, separated
by commas; for example, to delete the resource directory after one
hour, specify: #CreateTimeSpan(0,1,0,0)#
If
the value is set to 0, the resource directory persists until the
next server restart.
ColdFusion deletes the resource directory
only when format="HTML" and neither the name nor
filename attribute is specified. The default setting is 5 minutes: #CreateTimeSpan(0,0,5,0)#
|
style
|
Report
Builder
|
Optional
|
|
Style in CSS format that overrides a style
defined in the Report Builder report at run time. You can specify
an absolute file path, a file path relative to the report, or a
string in valid CSS format. For the styles to take effect, the style
names must match Style Name attributes assigned to elements in the
Report Builder report. You can generate a CSS file in Report Builder
and export it or you can create a CSS file with a text editor. For
a list of supported CSS styles, see the section Style properties.
|
template
|
Report Builder
|
Required
|
|
Specifies the pathname to the Report Builder
(CFR) file, relative to the web root.
|
timeout
|
Crystal Reports
|
Optional
|
|
Specifies the maximum time, in seconds,
in which a connection must be made to a Crystal Reports file.
|
type
|
Crystal Reports
|
Optional
|
standard
|
Type of report:
|
userName
|
Crystal Reports
|
Optional
|
|
Username required for entry into a database
from which the report is created. Overrides default settings for
data source in ColdFusion Administrator.
|
userPassword
|
Report Builder
|
Optional
|
|
(format="PDF" only) User
password.
|
UsageUse this
tag to generate a report using a report definition created in either ColdFusion
Report Builder or in Crystal Reports. (For more information on using the
ColdFusion Report Builder, display the online help by opening the
Report Builder and pressing F1.)
Note: The Excel
report output format type provides limited support for the formatting
options available in ColdFusion Reporting. Images and charts are
not supported and numeric data containing formatting (commas, percents,
currency, and so on) appear as plain text in Excel. The Excel output
format supports simple reports only and Adobe recommends that you
give careful design and layout consideration to reports designed
for Excel output.
This tag requires an end tag.
Using Cascading Style SheetsYou can override Cascading Style
Sheets (CSS) in Report Builder reports at run time by using the style attribute
of the cfreport tag in ColdFusion.
You can
create CSS files in one of two ways: by exporting styles with the
Export Report Styles icon in Report Builder or by creating a CSS
file in any text editor. For the CSS styles to take effect, however,
you must use Report Builder to assign the style names to the elements
in the report. (The exception is the default style: you can use
the style attribute to define the default style
in ColdFusion and apply it to the report even if the default style
is not defined in Report Builder.)
After you assign the style
names in Report Builder, you can update the style definitions in
the CSS file at any time and apply them at run time by using the cfreport and cfreportparam tags.
If your report contains subreports, the default style applies to
the master report and to all of the subreports. If the master report
uses CSS styles other than the default style, the CSS styles do
not apply to the subreports unless you specify them explicitly.
The
following code shows how to apply three different style sheets to
the main report and two subreports at run time:
<cfreport template="myreport.cfr" style="mystyle.css" format="PDF">
<cfreportParam subreport="subreport1" style="subreport1-style.css">
<cfreportParam subreport="subreport2" style="subreport2-style.css">
</cfreport>
The following code shows how to
apply a CSS style as a value of the style attribute:
<cfreport template="myreport.cfr" style='mystyle { defaultStyle: true; font-family:"Comic Sans MS"; color: ##00FF00; }' format="FlashPaper">
</cfreport>
The following code shows how to
create a variable called myStyle and use it as a value of
the style attribute:
<cfset mystyle='mystyle { defaultStyle: false; font-family: "Comic Sans MS"; }'>
<cfreport template="myreport.cfr" style="#mystyle#" format="HTML">
</cfreport>
Style attribute syntaxThe
style file or string must be valid CSS syntax. For more information,
see http://www.w3.org/Style/CSS/. The style must contain one or
more rule sets. Each rule set consists of a simple selector, which
is the Report Builder style name, followed by a declaration block,
which consists of a series of declarations separated by semicolons.
A declaration is a property:value pair.
If a selector contains
invalid syntax, ColdFusion ignores the selector and its declaration
block. Selectors and properties not supported by this feature are
ignored. Styles are case-insensitive, except parts not under the
control of CSS (such as font names).
The following example
shows the CSS definition for the default style:
DefaultStyle
{
default-style: true;
color: black;
font-family: Arial, "Comic Sans MS";
font-size: 16;
text-decoration: underline;
}
The following example shows the CSS definition
for a custom style called PurpleBoldItalicText:
PurpleBoldItalicText
{
color: purple;
font: italic bold 20px 30px Arial;
}
Identifiers for styles must be CSS2-compliant.
For example, CSS1 allows '_' in identifiers, but CSS2 does not.
In
CSS2, identifiers, including element names, classes, and IDs in
selectors, can contain only the characters A-Z, a-z, and 0-9. Also,
they can include ISO 10646 characters 161 and higher and the hyphen
character (-); however, identifiers cannot start with a hyphen or
a digit. They can contain escaped characters and any ISO 10646 character
as a numeric code. For example, you can write the identifier "B&W?"
as "B\&W\?" or "B\26 W\3F".
Style propertiesThe following table shows the style properties
exported by Report Builder:
Property name
|
Report Builder only
|
Valid values
|
Description
|
background-color
|
No
|
See the section Valid color values
|
Background color of the specified report
element, if the element is not transparent. The default background
color is white.
|
border
|
No
|
[border-width]
[border-style]
[border-color]
|
A shorthand property that specifies the border-width, border-style,
and border-color properties for all of the borders
in an element.
|
border-color
|
No
|
See the section Valid color values
|
Border color for text, images, and charts.
You can customize each side of the border. The default color is
white.
|
border-style
|
No
|
solid
dashed
none
|
A shorthand property that specifies the border-top-style, border-right-style, border-bottom-style, and border-left-style (the
comma-separated values must be in this order). If one or more values
are not specified, the value for the opposite side is used. If only
one value is listed, that value applies to all sides.
The none value
overrides the border-width value. Any other values,
including hidden, dotted, groove, ridge, inset, outset,
and double, are displayed as solid.
|
border-top-color
border-left-color
border-bottom-color
border-right-color
|
No
|
See the section Valid color values
|
Color of the element’s top, left, bottom,
and right border. For more details see that section Border and margin styles.
If
no border-color property is specified, the value
of the color property is used instead.
|
border-top-style
border-left-style
border-bottom-style
border-right-style
|
No
|
solid
dashed
|
Line style of the element’s top, left, bottom,
and right border. For more details see the section Border and margin styles.
Any
value other than dashed displays as solid.
|
border-top-width
border-left-width
border-bottom-width
border-right-width
|
No
|
thin
medium
thick
1px
2px
4px
|
Thickness of the top, left, bottom, and
right border of an element. Negative values are not valid. For more
details see the section Border and margin styles:
thin = 1/2 pt
medium = 2px
thick = 4px
|
border-width
|
No
|
thin
medium
thick
1px
2px
4px
|
A shorthand property that specifies the border-top-width,border-right-width,
and border-bottom-width properties with a single
property and value notation (the comma-separated values must be
in this order). If one or more values are not specified, the value
for the opposite side is used. If only one value is listed, it applies
to all sides:
thin = 1/2 pt
medium = 2px
thick = 4px
|
clip
|
No
|
auto
stretch
ratio
|
Specifies how images are resized:
auto: If the dimensions of the source image
differ from the element in the report, this attribute crops the
image to fit within the element boundaries. The image is not resized. Only
the part of the image that fits in the boundaries is displayed.
stretch: If the dimensions of the source
image differ from the element in the report, this attribute resizes
the image so that it fits within the element boundaries. If the dimensions
differ, the image is distorted.
ratio: If the dimensions of the source image
differ from the element in the report, this attribute resizes the
image to fit within the element boundaries but maintains the aspect ratio
of the source so that the image is not distorted.
|
color
|
No
|
See the section Valid color values
|
Color of the text (in text elements) and
the border (in graphic elements). The default color is black.
|
corner-radius
|
Yes
|
integer
|
Radius for arcs used to draw the corner
of rectangles. The default is 0 (square corners). Values less than
0 are interpreted as 0.
|
default-style
|
Yes
|
true
false
|
Default style for elements that do not or
cannot have a style applied. A subreport inherits its parent’s default-style
if it does not have one of its own.
|
embed-pdf-font
|
Yes
|
true
false
|
Specifies whether fonts are embedded in
the PDF document. Embedded fonts insure that the fonts display properly
even if the font is not installed on the system where the report
is viewed.
|
empty-cells
|
No
|
show
hide
|
Shows or hides a null value for text expressions:
show: If the text expression returns a null
value, the string "null" is displayed.
hide: If the text expression returns a null
value, the null value is replaced with an empty string. This is
the default.
|
font
|
No
|
[font-style]
[font-weight]
[font-size]
[line-height]
[font-family]
|
Font characteristic specifications. Use
this as a shorthand to specifying multiple property values; for
example:
font: italic 20px Arial;
Default
values for this property match those used for the individual properties.
Default values for the individual properties are applied to the
values omitted from the font property.
|
font-family
|
No
|
Comma-separated list of font names.
|
Group of fonts to apply to the element.
The first font found in the list is applied to the element. The
default is:
font-family: Arial, Helvetica, sansserif;
If
a font name contains spaces, enclose the name in quotation marks,
for example:
font-family: Courier, "Courier New", Arial;
|
font-size
|
No
|
[length]
|
Font size measured in points or pixels.
Negative values are not valid. The default value is 10 points. You
can specify points or pixels. 1 pixel = 0.75. points. This property
also is a component of the font property.
Standard CSS supports
other types of values not supported by Report Builder.
|
font-style
|
No
|
normal
italic
oblique
|
Font style. The italic and oblique values
are similar. The default value is normal. Also, this property is
a component of the font property.
|
font-weight
|
No
|
normal
bold
bolder
lighter
100
200
300
400
500
600
700
800
900
|
Font weight. Report Builder does not support
varying degrees of boldness or lightness; therefore, normal and lighter appear
as normal; all other values appear as bold.
The default is normal. Also, this property is a
component of the font property.
|
line-height
|
No
|
normal
[number]
[length]
[percentage]
|
Amount of space between consecutive lines
of text:
normal: Sets the line-height
to single-spacing (default).
number: A multiplier that determines the
line height as a factor of the element’s font size. To determine
the line height from this number, multiply the current element font-size
by the number. Negative values are not valid.
length: Sets the line height to an explicit
length. You can specify points (for example, "20") or pixels (for
example, "20px"). 1 pixel = 0.75 points. Negative values are not
valid. Standard CSS allows other units of length not supported by Report
Builder.
percentage: Defines the line-height as a
percentage. The percent symbol is required (for example, 150%).
Negative values are invalid.
|
line-size
|
Yes
|
none
thin
1px
2px
4px
dashed
|
Type of the border around a graphic element
or the type and the thickness of line elements. By default, lines
and rectangles have a 1-pixel border; thin is 0.05
pixels.
|
margin
|
No
|
[top-integer]
[right-integer]
[bottom-integer]
[left-integer]
|
Amount of blank space within the bounding
box of an element. This is a shorthand property that specifies the margin-top, margin-right, margin-bottom,
and margin-left properties with a single property
and value notation (the values must be in this order separated by commas.)
If one or more values are not specified, the value for the opposite
side is used. If only one value is listed, it applies to all sides.
For more details see the section Border and margin styles.
CSS
margins are transparent, which reveals the background of the parent
element. Negative values are valid; this allows for text overlays.
Examples:
margin: 10,20,30,40;
margin: 10;
margin: 10,20,30;
|
margin-top
margin-left
margin-bottom
margin-right
|
No
|
integer
|
See margin.
|
parent-style
|
Yes
|
styleName
|
Name of the parent report style from which
this style inherits some or all of its properties. The style name
must be defined in either the report or before this style definition
in the CSS file or text.
|
text-align
|
No
|
left
center
right
justify
|
Alignment of text and images on the horizontal
axis. The default value is left.
|
text-decoration
|
No
|
underline
line-through
underline line-through
|
Text characteristics not defined with the font-style and font-weight properties.
The color of the text-decoration is determined by the color property
for the element. Unknown values are ignored.
|
text-rotation
|
Yes
|
none
left
right
|
Rotation of text elements. Use it to change
the text direction by rotating it 90 degrees to the right or left.
|
transparency-mode
|
Yes
|
opaque
transparent
|
Transparency of elements. Graphic elements,
such as rectangles and lines, are opaque by default, but images
are transparent. Subreport elements, static text, and text fields are
transparent by default.
|
vertical-align
|
No
|
top
middle
bottom
|
Alignment of text and images on the vertical
axis. The default value is top.
|
xhtml-formatted-text
|
Yes
|
true
false
|
Specifies whether the text element contains
XHTML-compatible instructions:
true:
The text element contains xhtml-compatible instructions, for example,
<b>My Text Label</b>. In this example, the text within
the tags displays in bold (My Text Label), and the tags (<b>
</b>) are not displayed.
false: The text element does not contain
xhtml-compatible instructions; therefore, all the text within the
text element is displayed. This is the default.
|
Styles or values that are not supported
by Report Builder are ignored in the report, in which case, if a
default-style is defined, Report Builder applies the default style
to the element.
Valid color valuesYou
can specify a color as #RRGGBB. This represents a color that uses
a triplet of hexadecimal values concatenated together. The values
represent the red, green, and blue components for a given color.
The range of each component value is 00-FF in hexadecimal. Also,
you can use one of the 140 X11 color names (see http://www.blooberry.com/indexdot/color/x11makerFrameNS.htm).
The color name is case-insensitive. This set of names assigns names
to specific RGB values. Also, a color name can also be specified
as ##RGB, rgb(r,g,b), or rgb(r%,g%,b%). See CSS Color Units for
syntax details (see http://www.blooberry.com/indexdot/css/syntax/units/color.htm).
UI Name is not supported.
The following example shows the
different ways you can represent the color lime:
color:lime
color:#00FF00
color:#0F0
color:rgb(0,255,0)
color:rgb(0%,50%,0%)
If you specify a color in hexadecimal
format as part of the style attribute for the cfreport tag,
use the format ##00FF00. For example:
<cfreport template="myreport.cfr" style='mystyle { defaultStyle: true;
font-family:"Comic Sans MS"; color: ##00FF00; }' format="HTML"/>
Border and margin stylesUse the border-width, border-style, border-color, and margin properties
when all four sides of the element have the same value. You can specify
from one to four parameters for these properties:
Number of parameters
|
Example
|
Result
|
1
|
border-width: thick
|
Parameter applied to all four sides of the
element’s border.
|
2
|
border-width: thick, thin
|
First parameter (thick)
applied to the top and bottom sides; second parameter (thin) applied
to the left and right sides.
|
3
|
border-width: thick, thin, medium
|
First parameter (thick)
applied to the top; second parameter (thin) applied
to the left and right sides; third parameter (medium)
applied to the bottom.
|
4
|
border-width: thick, thin, medium, thick
|
First parameter (thick)
applied to the top; second parameter (thin) applied
to the right side; third parameter (medium) applied
to the bottom; fourth parameter (thick) applied
to the left side.
|
You can use the properties for each side
of a border to override the style specified by the border-width, border-style, border-color,
and margin properties.
ExampleExample
1: This example shows the use of cfreport for the ColdFusion Report Builder.
<cfquery name="northwindemployees" datasource="localnorthwind">
SELECT EmployeeID, LastName, FirstName, Title, City, Region, Country
FROM Employees
ORDER BY Country, City
</cfquery>
<CFREPORT format="PDF" template="FifthReport.cfr"
query="#northwindemployees#"/>
Example 2: This view-only example shows the use
of cfreport for Crystal Reports.
<h3>cfreport Tag<h3>
<p>cfreport lets reports from the Crystal Reports Professional report writer display through a ColdFusion interface. To run, the tag requires the name of the report. cfreport can also pass information to the report file displayed, to change the output conditions.</p>
<p>This example would run a report called "monthlysales.rpt " and pass it an
optional filter condition to show only the information for a subset
of the report.</p>
<cfreport report = '/reports/monthlysales.rpt'>
{Departments.Department} = 'International'
</cfreport>
<p>Substitute your report files and filters for this code. cfreport can put Crystal Reports into web pages.</p>
|