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 the cfusion server in the multiserver configuration, 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.

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.

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.

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.