For installation instructions, see Installing ColdFusion. When you install the Report Builder, it also registers Windows DLLs that RDS uses. If these DLLs fail to register properly, the Report Builder generates errors at startup and when using RDS.
Setup Wizard
The first time you start the Report Builder, it runs the Setup Wizard. The Setup Wizard prompts you to define default settings for an associated ColdFusion server. These settings include the following:
- Default unit of measurement: Inches, centimeters, or pixels.
- ColdFusion server. The RDS server that the Query Builder and Chart Wizard use to access database data (RDS must be enabled on this server). The Setup Wizard requires the following information:
- Host name or IP address.
- Web server port. Typically, the port is 80 if you are using a web server connector, 8500 if you are using the built-in web server in the server configuration, 8300 if you are using the built-in web server with an instance created with the ColdFusion Enterprise Instance Manager, or a J2EE-server-specific web server port number.
- RDS password for the associated ColdFusion server.
- Directory path to the web root used by the associated ColdFusion server (for example, C:\Inetpub\wwwroot or C:_ColdFusion_\wwwroot).
- URL for the web root used by the associated ColdFusion server (for example, http://localhost or http://localhost:8500).
After running the Setup Wizard, the Report Gallery dialog box appears. When you click the Using A Report Wizard radio button, the Report Builder runs the Report Creation Wizard, which prompts you for information and automatically generates a complete report definition.
For more information on the Report Creation Wizard, see the Report Builder online Help.
Configuring RDS
Configure one RDS server for each ColdFusion server for which you define reports. After you configure an RDS server, you can use the Query Builder to access data sources that you defined in the associated ColdFusion server, and select database columns for use as query fields in a report.
Add an RDS server
- Open the Preferences dialog box by selecting Edit > Preferences from the menu bar.
- Click Server Connection.
- Click the plus sign (+) next to the pop-up menu in the upper-left corner of the dialog box.
- In the Configure RDS Server dialog box, specify the following information, and then click OK:
- Description A name for the server connection. This name appears in the pop-up menu on the left side of the Query Builder.
- Host name The host on which ColdFusion runs. Type localhost or an IP address.
- Port Web server port number. Accept the default port (80) or enter the port number of the ColdFusion server's built-in web server (8500 is the default port number).
- Context Root (J2EE configuration only) The context root (if any) for the ColdFusion web application.
- Use Secure Sockets Layer (Optional) Enables SSL security.
- User Name Not applicable to ColdFusion RDS.
Password RDS password. You set this password in the ColdFusion Administrator.
Note: Do not confuse the RDS password with the ColdFusion Administrator password, which you also manage through the ColdFusion Administrator.
- Prompt for password Specifies whether to prompt for an RDS password each time you use the Query Builder. If you select this option, leave the User Name and Password fields blank.
Designate a default RDS server
- Open the Preferences dialog box by selecting Edit > Preferences from the menu bar.
- Click Server Connection.
- Select an RDS server from the Preferred RDS Server pop-up menu, and click OK.
The Report Builder automatically connects to the specified server when you display the Query Builder or Chart Wizard.
User interface usage, tips, and techniques
The Report Builder workspace includes the following areas:
- Toolbox: Contains nonvariable elements placed in a report, including text, shapes, images, subreports, and graphs. To use toolbox elements, click the element, and then drag in the report band to define the element's size. After you place an element on a report band, you can modify its appearance and behavior by using the Properties panel.
- Alignment panel: Use Control-click or Shift-click to select multiple elements in a report band, and then click the appropriate alignment icon. You can also use Control+A to select all elements in a report band.
- Report bands: Place toolbox elements, query fields, and calculated fields on report bands. The default report bands are report header, page header, column header, page footer, report footer, and watermark. Page header, page footer, and watermark are closed by default; to open them drag one of the adjacent splitter bars. To define additional bands for groups, select Report > Group Management.
ColdFusion provides three panels that you use to place and format data elements in the workspace:
-
- Properties panel: Contains display and report characteristics for the selected field. To display the Properties panel, choose Window > Properties Inspector from the main menu. To change a property value, type or select a new value, and press Enter. For complete information on properties, see the Report Builder online Help.
- Fields and parameters panel: Contains items for query fields, input parameters, and calculated fields. To display the Fields and parameters panel, choose Window > Fields and Parameters from the main menu. Use the add, edit, and delete icons to manage these fields. After you define a field, drag the field name to add the field, its associated label, or both, to a report band.
- Report styles panel: Contains the styles that you define for a report. To display the Report styles panel, choose Window > Report Styles from the main menu. Use the add, edit, and delete icons to manage report styles. After you define styles, you apply them to elements on the report instead of specifying font, font size, and so on, for each individual element. If your report layout, platform, or font availability requirements change, you can modify the style to apply the changes throughout the report. Additionally, you can specify a style as the default for the report: if no other style is applied to an element in the report, Report Builder applies the default style to that element.
The View menu lets you control whether toolboxes and panel windows appear. Also, you can click 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 the tabs at the top of the window. To redock 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 and the online Help.
Report definition guidelines
To ensure a successful report, 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 must be in the report? Where does it come from? Whether you use the Query Builder or pass a query to the report, 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 totaled 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.
- 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.
- 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, use this option if your application has a form that your clients use to construct dynamic selection criteria.
- Related visual information:
- Charts For more information, see Using charts.
- Subreports For more information, see Using subreports.
Managing fonts with printable reports
Ideally, reports achieve a consistent look across all client platforms and all browsers. ColdFusion handles this consistency 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. A variety of factors ensure a consistent report display.
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, 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, 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/cfusion/lib/cffont.properties file. (In the JEE configuration, this file is in 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.
Note: 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.