ColdFusion Developer’s Guide phần 8 potx

ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 822 The View menu lets you control whether toolboxes and panel windows appear. Also, you can click on a window’s title to undock it and drag it to another area of the screen. For example, you can drag all three panels and dock them in the same window. Report Builder lets you switch between them by clicking on the tabs at the top of the window. To re-dock a tool window or panel, drag it to the side or corner until a rectangle appears, and then release the mouse button. For more information, see “Common reporting tasks and techniques” on page 823 and the online Help. Report definition guidelines To ensure a successful report, you should plan the following before defining it in the ColdFusion Report Builder: • Report design issues: Audience: Why are you creating this report? Who is the audience? Data: What data needs to be in the report? Where does it come from? Whether you use the Query Builder or pass a query to the report, you should plan the data in advance. Grouping: Are groups required? If so, ensure that the result set is returned in the correct order, and you define a group based on the sort column. Calculated fields: Are there fields that must be totalled or calculated? For column totals, use calculated fields. For calculated totals on individual rows, use SQL. For more information, see “Common reporting tasks and techniques” on page 823. Input parameters: Does the report require variable input? If so, define an input parameter and pass values to the report at run time by using the cfreportparam tag. For more information, see “Common reporting tasks and techniques” on page 823. • Data retrieval strategy: Query Builder and basic SQL: Use this option when your report has standard selection criteria (such as a WHERE clause with sorting and a fixed set of selection criteria) and when you have to develop a report quickly. This method also lets you specify cfquery options, such as caching. Query Builder and advanced query mode: Use this option when you use a ColdFusion query encapsulated in the report definition. This option is also useful if the query comes from the cfdirectory, cfldap, or cfpop tags; query of queries; or is dynamically constructed with the QueryNew function. The cfreport tag and a passed query: Use this option when you require more control over the result set used in the report; for example, your application might have a form that your clients use to construct dynamic selection criteria. • Related visual information: Charts: For more information, see “Using charts” on page 837. Subreports: For more information, see “Using subreports” on page 838. Managing fonts with printable reports Ideally, reports should achieve a consistent look across all client platforms and all browsers. ColdFusion handles this automatically for graphics and images, using the size specifications in the report definition. However, potential differences in font availability across browsers, browser versions, languages, and platforms can affect the font display for your report. There are a variety of factors that you must understand to ensure consistent report display. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 823 Embedded fonts You can ensure consistent report display by embedding fonts. However, reports with embedded fonts have a larger file size. Output format The FlashPaper and PDF output formats handle embedded fonts differently. FlashPaper: FlashPaper always embeds fonts, which ensures that reports always display appropriately. PDF: PDF reports can optionally embed fonts, however, if your report doesn't use embedded fonts, you must ensure that the fonts are available on the client computers. Font availability on the server computer and the client computer ColdFusion has different requirements for rendering the fonts in a report, depending on where the fonts are located. Server computer: For all formats, the fonts used in a report must reside on the computer that runs ColdFusion. ColdFusion requires these fonts to render the report accurately. ColdFusion automatically locates Acrobat built-in fonts and fonts stored in typical font locations (such as the Windows\fonts directory). However, if your server has additional fonts installed in nonstandard locations, you must register them with the ColdFusion Administrator so that the cfdocument and cfreport tags can locate and render PDF and FlashPaper reports. Client computer: If your PDF report does not embed fonts, the fonts reside on the client computer to ensure consistent report display. Mapping logical fonts to physical fonts If you are using Java logical fonts, such as serif, sans serif, or monospaced, ColdFusion maps these fonts to physical fonts by using specifications in the cf_root/lib/cffont.properties file (on the multiserver or J2EE configuration, this is the cf_webapp_root/WEB-INF/cfusion/lib directory). You can modify these mappings, if necessary. Also, if you are using an operating system whose locale is not English, you can create a locale-specific mapping file by appending .java-locale-code to the filename. If ColdFusion detects that it is running on a non-English locale, it first checks for a cffont.properties.java-locale-code file. For example, on a computer that uses the Chinese locale, name the file cffont.properties.cn. For more information on Java locale codes, see the Sun website. The ColdFusion install includes a cffont.properties.ja file for the Japanese locale. This discussion applies to both the cfdocument and cfreport tags. For more information, see the Report Builder online Help. Common reporting tasks and techniques With Report Builder, you can include data in reports in a variety of formats, and perform calculations on the infor- mation. For more information, including troubleshooting tips, see Report Builder online Help. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 824 Grouping and group breaks You can add clarity to a report’s organization by grouping the information. You can define separate headings for each new group and also display group-specific summary information, such as subtotals at the end of each group’s area of the report. For example, you might create a report that displays departments, employees, and their salaries. Grouping the data by department lets users quickly understand department salary characteristics. When the department ID changes, the ColdFusion Report Builder triggers a group break. The group break completes the old group by displaying the group footer and starts the new group by displaying the group header. The ColdFusion Report Builder does not group data itself. You must ensure that the SQL used to retrieve the result set is already grouped in the appropriate order; typically you implement grouping by specifying an ORDER BY clause in the SQL SELECT statement used for the report. For example, you might use the following SQL SELECT statement: SELECT EmployeeID, LastName, FirstName, Title, City, Region, Country FROM Employees ORDER BY Country, City For this example, you can define two groups: one that corresponds to Country, and a second group that corresponds to City. When you define more than one group, the Group Management dialog box appears with Up Arrow and Down Arrow keys, which you can use to control group hierarchy. For example, country should be above city, because countries contain cities. Define a group 1 Select Report > Group Management from the menu bar. 2 Click Add. 3 Specify a group name in the Name field. 4 Specify the value that controls grouping (also called a group expression) in the Group on field. At run time, ColdFusion triggers a group break when the result of this value changes. These values are often query field names. However, this value can also be a calculated field or other type of expression. Sample group expressions include the following: Query field: Creates a group break when the associated column in the result set contains a different value. The field that you specify must be one of the sort criteria for the result set; for example, query.country. Calculated field: Creates a group break when a calculated field returns a different value. For example, if the expression calc.FirstLetter returns the first letter of a query column, you can group a report in alphabetical order. Boolean expression: Creates a group break when a Boolean expression returns a different value. For example, if your result set is sorted by the passpercentage column, you might use the Boolean expression query.passper- centage LT 50. 5 Specify group break options: Start New Column: Forces a new column on a group break. Start New Page: Forces a new page on a group break. Reset Page Number: Resets the page number to 1 on a group break. 6 Specify band size and printing information: Min. height for group: The minimum height that must remain on a page for ColdFusion to print the group band on that page. Reprint Header on Each Page: Displays the group header on each page. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 825 7 Click OK. The Report Builder adds the group to the report and creates header and footer bands for the group. 8 Click OK again. 9 Add headings, text, query fields, calculated fields, and other information to the group’s header and footer. Create group subtotals 1 Create a calculated field to contain the group subtotal. Create the calculated field that uses the following criteria: • Specify a numeric data type. • Select Sum in the Calculation field. • Specify the field to sum on in the Perform Calculation On field. For example, on an employees by department report, you might sum on query.emp_salary. • Specify that the field should be reset when the group changes. 2 Place the calculated field on the report. For more information on calculated fields, see the Report Builder online Help. Defining, modifying, and using fields and input parameters The Report Builder supports variable data through query fields, input parameters, and calculated fields, as follows: Query field: Maps to columns in the database result set associated with the report. You define one query field for each column in the associated database query. Calculated field: Analyzes or sums multiple detail rows in a report. ColdFusion dynamically generates calculated field values at report-generation time, optionally recalculating the value with each new report, page, column, or group. Input parameter: Specifies data fields that you pass to the report at run time through the cfreportparam tag or from a main report to a subreport. You can place input parameters directly on a report band or you can use them as input to a calculated field. Define a query field 1 Choose Window > Fields and Parameters. 2 Click Query Fields. 3 Click the plus sign (+) at the upper edge of the tab. 4 Type a value for the name field. This must match a column name in the corresponding cfquery statement and cannot contain a period. 5 Type a default label. 6 Specify the data type of the corresponding database column, as follows: Object Time Long Boolean Double Short ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 826 7 Click OK. Note: The Query Builder defines query fields automatically for all database columns in the result set (this does not apply to the Advanced Query Builder). Also, if you run the Query Builder as part of the Report Creation Wizard, the wizard places query fields on the report. Define a calculated field 1 Choose Window > Fields and Parameters. 2 Click Calculated Fields. 3 Click the plus sign (+) at the upper edge of the tab. 4 Specify a name, default label text, and data type. Data type options are the same as for query fields. 5 Specify calculation options: Calculation: Specifies the type of calculation that ColdFusion performs. Valid values are: Average, Count, DistinctCount, First, Highest, Lowest, Nothing, Standard Deviation, Sum, System, and Variance. If you specify Nothing, you typically use the Perform Calculation On field to specify a dynamic expression. With the exception of Nothing (for which you use the Perform Calculation On field) and System (for which you write a customized scriptlet class), you use these calculations for group, page, and report totals. Perform Calculation On: Specifies a field or expression. Click the button to display the Expression Builder. Initial Value: Specifies an initial value for the calculated field. 6 Specify the following reset options, and click OK: Reset Field When: Specifies when to reset the calculated field value. Valid values are: None, Report, Page, Column Group. Reset Group: If Reset Field When is set to Group, use this field to specify the group whose group break triggers the reset. For additional information on calculated fields, see the Report Builder online Help. Define an input parameter 1 Choose Window > Fields and Parameters. 2 In the Fields and Parameters panel, click Input Parameters. 3 Click the plus sign (+) at the upper edge of the tab. 4 In the Add Input Parameter dialog box, enter a value for the name field. This must match an input parameter, such as the name attribute of a cfreportparam tag included in the cfreport tag that invokes the report definition. 5 Enter the default label text. 6 Specify a data type and default value, and click OK. Data type options are the same as for query fields. For more information on using input parameters, see “Using input parameters to pass variables and other data at run time” on page 834 and “Using subreports” on page 838. Byte Float Big Decimal Date Integer String Time Stamp BLOB CLOB ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 827 Place a query field, calculated field, or input parameter on a report band 1 In the Fields and Parameters panel, use the radio buttons to specify whether to place the label, the field, or both. 2 Drag the query field, calculated field, or input parameter from the Fields and Parameters tab to the appropriate report band. 3 Drag the query field, calculated field, or input parameter to the desired band. 4 (Optional) Use the Properties panel to customize the field display. For example, you might have a query field named query.emp_salary and a calculated field that sums query.emp_salary, resetting it with each group. Place query.emp_salary in the detail band, and the associated calcu- lated field in the group footer band. Using toolbox elements on report bands You use the toolbox to add graphic and textual elements, such as images, circles, squares, lines, dynamic fields, charts, and subreports, to report bands. The basic technique for adding toolbox elements is to click in the toolbox element and then drag to define an area in the appropriate report band. For some toolbox elements, such as image and text box, a dialog box immediately appears, prompting for more information. For all toolbox elements, you customize the appearance of the element by using the Properties sheet. You can add toolbox elements from the Insert menu. For information on charts, see “Using charts” on page 837. For information on subreports, see “Using subreports” on page 838. Create a text box 1 Click the Label icon (abc) in the toolbox. 2 Define the area for the label by dragging on the desired band. 3 Enter the label text in the Edit Label Text dialog box. To add a line break, press Control+Enter. 4 Click OK, or press Enter. Note: ColdFusion trims leading and trailing blanks from labels. To include leading and trailing blanks, define a dynamic field and include the blanks in the expression, for example, " My Title ". Import image files 1 Click the Image icon in the toolbox. 2 Define the area for the image by dragging on the desired band. 3 In the Image File Name dialog box, navigate to the file that contains the image, select the file, and click OK. Use a database BLOB column as an image source 1 Click the image icon in the toolbox (the icon has a tree on it). 2 Define the area for the image by dragging on the desired band. The Image File Name dialog box appears. You can also drag the BLOB field from the Fields and Parameters tab to a report band. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 828 3 Click Cancel. The Expression Builder appears. 4 Click the Image Type pop-up menu and change File/URL to BLOB. 5 Select the query field or input parameter that contains the BLOB column. Note: The BLOB column must contain a binary image in GIF, JPEG, or PNG format. 6 Click OK. Note: These instructions assume that the contents of the BLOB column can be rendered as an image. Add rectangles, ellipses, and lines 1 Click the rectangle, ellipses, or line icon in the toolbox. 2 Define the area or line by dragging on the desired band. 3 Resize the selected element by dragging the handles that surround it. Pressing the Control key while resizing a rectangle, ellipsis, or line, constrains the element to a square, circle, or angles that are multiples of 45 degrees. Add dynamic fields 1 Click the Field icon in the toolbox. 2 Define the area for the dynamic field by dragging on the desired band. The Add Field dialog box appears (if you haven’t defined any query fields, the Expression Builder appears). 3 Select the field to add. If you select a query field, calculated field, or input parameter, this is the same as dragging from the Fields and Parameters tab. 4 (Optional) Select Manually Entered Expression. The Expression Builder appears. This option is useful for calculations that use variables in the same row. For example, to compute total price for an order detail line item, you might use the following expression: LSNumberFormat((query.unitprice * query.quantity), ",_.__") 5 Click OK. Aligning elements Organized element layout is essential to a visually pleasing report. You achieve this organization by aligning, spacing, and centering visual elements on each band relative to each other, to the band itself, and to elements on other bands. The Report Builder Align Palette includes the following options: • Align left, center, and right • Align top, horizontal, and bottom • Same heights, widths, and both • Space equally horizontally • Space equally vertically You align, size, and space multiple report elements, as follows: ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 829 Relative to the band they are in: You control relative alignment through the Align to Band icon, which is the bottom icon in the Align Palette. When it is enabled, the Align to Band icon has a rectangle surrounding it, and the Report Builder aligns and spaces one or more elements relative to the height and width of the band. Relative to each other: When Align to Band is disabled, Report Builder aligns and spaces two or more elements relative to each other. Use the Align Palette 1 Select two or more elements by pressing Control-click, Shift-click, or using lasso select. 2 Click the alignment icon, or select Modify > Alignment > alignment option from the menu bar. The Align Palette options are also available from Modify > Alignment on the menu bar. For complete information on fine-tuning element display, see the Report Builder online Help. Using report styles A report style is similar to a font style in Microsoft Word. Instead of explicitly associating an element with formatting specifications, you associate the element with a style. This provides you with report-wide control of the formatting characteristics of your report. Additionally, you can specify style that is the default for the report. The ColdFusion Report Builder uses the default style for all fields for which you have applied no other font specifications or styles. The default style, if defined, is displayed in bold in the Report Styles panel. Report Builder also lets you import styles from a Cascading Style Sheet (CSS) file and export styles defined in Report Builder to a CSS file. This way you can enforce standard formatting across reports and override styles at run time from a CFM page. For more information, see “Using Cascading Style Sheets” on page 849 and the CFML Reference. Note: When choosing fonts for your report, you must ensure that the fonts are available on the server that runs ColdFusion and (if you don’t embed fonts) on the client computer. For more information on fonts, see “Creating a simple report” on page 840. Define a style 1 Choose Window > Report Styles. 2 Click the (+) icon at the upper edge of the Report Styles tab. 3 Type a value for the Name field. Style names must be unique. 4 Add other style characteristics, and click OK. Specify a style as the default 1 Edit an existing text style or create one. 2 Select the option with this label: This is the default style if no other style is selected for an object. 3 Add or modify other text style characteristics, and click OK. Apply a style to a report element 1 Select the element in the report band. 2 Choose Window > Properties Inspector. 3 Choose the style from the Style pop-up menu. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 830 For more information, see the Report Builder online Help. Previewing reports Report building is an iterative process and most developers periodically display the in-progress report to review their most recent changes. If your report uses an internal query and you established default web-root settings, preview functionality is enabled automatically. If your report uses a passed query, you must define an associated CFM page and associate that page with the report. The Report Builder invokes this page when you request Report Preview. Preview a report that uses an internal query 1 (Optional) Define default server connection information using the Preferences dialog box, if you did not define these settings previously: • Default RDS server configuration (used for Query Builder and Chart Wizard only; not required for report preview). • Fully qualified path for the local web root directory; for example, C:\ColdFusion\wwwroot or C:\Inetpub\wwwroot. • URL for the local web root, for example, http://localhost:8500 or http://localhost. 2 (Optional) Specify the output format in the Report Properties dialog box (the default format is FlashPaper). 3 (Optional) If your report is designed to be invoked by a CFM page, specify the URL of the CFM page in the Report Properties dialog box. 4 Save your report. 5 Select File > Preview from the menu bar to display the report. Note: If the Report Builder displays the Edit Preview Report URL dialog box instead of displaying the Preview window, select Edit > Preferences from the menu bar and insure that the web root file and URL settings are correct on the Server Connection pane. 6 Close the preview window by pressing F12. If your report is designed to accept a query object from a cfreport tag, you must associate a URL with the report. If necessary, the Report Builder prompts for this URL when you preview the report. Otherwise, you can open the Report Properties dialog box, and specify the URL of the CFM page in the Report Preview URL field. You can use the cfreport tag to invoke a report, regardless of whether the report has an internal query or is passed a query. Preview with an associated CFM file 1 Select Report > Report Properties from the menu bar. 2 Specify the URL of the associated CFM page in the Report Preview URL field. This CFM page must contain a cfreport tag whose template attribute specifies the current CFR file and, if necessary, passes a query in the query attribute. 3 Save your report. 4 Press F12. Depending on the output format that you have chosen, the Preview Report window displays your report in PDF, FlashPaper, RTF, XML, HTML, or Excel format. Displaying page numbers The Report Builder includes a built-in calculated field named PAGE_NUMBER, which displays the current page number when you place it on a report band. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 831 Add a built-in calculated field 1 Click the Field tool in the toolbox. 2 Drag in the center of the header or footer band to define the size of the page number field. The Add Field dialog box appears, listing all fields defined for the report, including built-in calculated fields and input parameters. 3 Select calc.PAGE_NUMBER, and click OK. You can use the Field tool to add any type of field (query field, calculated field, input parameter) to a report. For information on the other built-in calculated fields, see the Report Builder online Help. Using layered controls Layered controls are elements that you place at the same location of a report band, and then use PrintWhen expres- sions to conditionally display one or the other at run time. You can use layered elements to customize the circum- stances under which the elements display and enhance a report’s ability to communicate important information. Place an element directly over another element 1 Place the elements on the band. 2 Choose Window > Properties to display the Properties panel. 3 Specify a PrintWhen expression, display properties, and placement properties for each element using the Properties panel, as follows: 4 Specify a PrintWhen expression for each element. For example, you might specify the following expression to display one element when shippeddate is later than requireddate (that is, late) and another element when shippeddate is earlier than requireddate: First element: query.shippeddate LTE query.requireddate Second element: query.shippeddate GT query.requireddate 5 Specify different display characteristics for each element. For example, if an order is late, display it in red text. 6 Set the Top, Left, Height, and Width properties to the same values for each element. When you specify identical placement properties, you access the individual elements through the Layered Controls menu. Use the Layered Controls menu 1 Right-click on the top element. 2 Select Layered Controls > elementname from the pop-up menu. The Report Builder identifies each layered element by displaying its PrintWhen expression. 3 Select the element and choose Window > Properties Inspector to view the element properties. Using links You can include hyperlinks from query fields, calculated fields, input parameters, charts, and images to a variety of destinations: • An anchor or page within the same report • An anchor or page within another report [...]... specified in the cfchart, cfchartseries, and cfchartdata tags For more information on these tags, see the CFML Reference ADOBE COLDFUSION 8 8 38 ColdFusion Developer’s Guide For complete information on ColdFusion charting capabilities, see “Creating Charts and Graphs” on page 785 For more information on charting using the Report Builder, see Report Builder online Help Using subreports Subreports let you... code: 4 ReportTitle { color:Black; font-size:24pt; } CompanyName { color:#6 188 A5; font-weight:bold; } PageTitle { color:#333333; font-size:14pt; font-weight:bold; } ReportDate { color:#333333 } SubTitle { color:#6 089 A5; font-size:12pt; font-weight:bold; } DetailLabel { color:Black; ADOBE COLDFUSION 8 851 ColdFusion Developer’s Guide background-color:#E3EDEF; font-weight:bold; } DetailData { default-style:true;... style to report title 3 4 Press F12 to preview the report ADOBE COLDFUSION 8 852 ColdFusion Developer’s Guide Overriding report settings at run time You can use the cfreport tag in ColdFusion to override report settings in a Report Builder report at run time The examples use the CFR file that you created in “Creating a simple report” on page 84 0 Overriding the report query This example filters the data... directory where it stores all of the image files in the report (charts are saved as PNG files) The location of the temporary directory is: C: \ColdFusion8 \tmpCache\CFFileServlet\_cfreport\_report[unique_identifier] ADOBE COLDFUSION 8 853 ColdFusion Developer’s Guide You can specify when the temporary directory is removed from the server by using the CreateTimeSpan function as a value for the resourceTimespan... to files, double-click the index.htm file Note: ColdFusion does not overwrite the files referenced by the slides in the presentation; changes to the generated presentation files do not affect the source files ADOBE COLDFUSION 8 856 ColdFusion Developer’s Guide Adding presenters Optionally, you can add one or more presenters under the cfpresentation tag ColdFusion displays the presenter information in... automatically creates and applies the following styles to your report: • ReportTitle ADOBE COLDFUSION 8 850 ColdFusion Developer’s Guide • CompanyName • PageTitle • ReportDate • SubTitle • DetailData (default style) • DetailLabel • PageFooter • RectangleStyle • LineStyle The instructions on “Adding and formatting fields” on page 84 4 show how to add a field called GroupFooter and apply it to a text field and a... Subreport Parameters property ADOBE COLDFUSION 8 840 ColdFusion Developer’s Guide b Click the button c Add, modify, or delete subreport parameters, and click OK Creating a simple report The following example shows how to create a simple report by using the Report Wizard and then modifying it The example uses the cfartgallery database, which is installed with ColdFusion The example shows how to perform... change the Transparency to Transparent b Under Formatting, change Scale Image to Retain Shape 8 In the Header band, control-click the logo image and the Sales Report text box in the work space to select them 9 Click the Align Left Sides icon in the Controls toolbox ADOBE COLDFUSION 8 846 ColdFusion Developer’s Guide 10 Choose File > Save to save your changes 11 Press F12 to preview the report 12 Close... b In the Default Label Text field, type Unsold c In the Data Type field, choose Big Decimal from the pop-up menu d In the Calculation field, choose Sum from the pop-up menu ADOBE COLDFUSION 8 8 48 ColdFusion Developer’s Guide e In the Perform Calculation On field, enter the following expression to calculate the dollar amount of unsold art: Iif(IsBoolean(query.ISSOLD) and not(query.ISSOLD), query.Price,0)... 85 6 Adding slides 85 7 Sample presentations 85 8 About ColdFusion presentations ColdFusion lets you create dynamic slide presentations from source files and from CFML and HTML code on a ColdFusion page You can use . run time” on page 83 4 and “Using subreports” on page 83 8. Byte Float Big Decimal Date Integer String Time Stamp BLOB CLOB ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 82 7 Place a query field,. CFML Reference. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 83 8 For complete information on ColdFusion charting capabilities, see “Creating Charts and Graphs” on page 785 . For more information. the BLOB field from the Fields and Parameters tab to a report band. ADOBE COLDFUSION 8 ColdFusion Developer’s Guide 82 8 3 Click Cancel. The Expression Builder appears. 4 Click the Image Type pop-up