Using The ColdFusion Report Builder

The ColdFusion Report Builder creates and edits a special ColdFusion file with a .cfr extension. Unlike .cfm and .cfc files, .cfr files cannot be edited with a text editor, and the ColdFusion Report Builder must be used. .cfr files are report templates that may be used as is, or invoked from CFML code as needed (as will be explained below).

NOTE

The ColdFusion Report Builder is a Windows only utility. Reports created using the Report Builder can be processed by ColdFusion on any platform, and reports can be viewed on all platforms too. However, at this time reports can only be created on Windows machines.

Report Builder Features

Key ColdFusion Report Builder features include:

• Familiar report designer interface.

• Tabbed MDI interface (allows for multiple reports to be edited at once).

• Data grouping via bands.

• Subreport support.

• SQL query builder (requires an RDS connection).

• Charting wizard (requires an RDS connection).

• Report preview (is using an embedded query).

• Access to CFML expressions (with integrated expression builder),

• Styles to manage output.

• Extensive integrated help.

Navigating The Report Builder

The ColdFusion Report Builder screen looks a lot like other report writing tools that you may have used. The screen contains several sections that you should be aware of:

• The large open space in the middle of the Report Builder is where reports are defined and edited.

• On the left is a toolbox containing buttons to insert images, fields, sub-reports, and more into reports, as well as buttons used to manage element alignment.

• On the top of the screen are toolbars for file opening, editing, fonts, etc.

• On the upper right is the Properties panel, this displays the properties for any report item, and allows for quick property editing.

• On the bottom right is the Fields and Parameters panel, used to access query columns, calculated fields, and input parameters.

Creating A Report

To create a new report, click on File, New to display the ColdFusion Report Builder Gallery dialog box. (This box will be displayed automatically if the Report Builder is started without clicking on a .cfr file).

You will be presented with two options:

• As A Blank Report: Select this option to create a blank report for you to work with.

• Report Creation Wizard: Use this option to launch an interactive Wizard that will prompt you for the SQL, grouping, layout, and more, generating a complete usable report (that you can then edit and tweak as needed).

Whichever option is used, the first task will be to specify the SQL query columns to be used within the reports. This can be via an actual SQL statement (entered manually or created via the SQL Query Builder) or a list of column names manually specified in the Fields and Parameters panel. Once query column have been defined they can be used within the report.

NOTE

Embedded SQL is the default report SQL statement, and it can be overridden at runtime via <cfreport query="">.

TIP

It is only necessary to actually embed SQL within the .cfr file if you want to support direct execution of the .cfr file (as opposed to programmatic execution via <cfreport>). However, there is one big advantage of embedding SQL (regardless of the planned invocation method), previewing of the report from within the Report Builder is only possible if a default SQL statement exists.

Editing A Report

To edit an existing .cfr file, either double-click on it (from within Dreamweaver or Windows Explorer), or launch the Report Builder and select the .cfr file from the recent list (or simply browse to it and open).

Report elements may be edited and modified as needed. To rerun the wizard that created the report (assuming that the wizard was in fact used), Report, Report Wizard For This Report.

TIP

It is generally not a good idea to rerun the wizard after you have made changes to a report. If you need access to the SQL Query Builder portion of the wizard, use Report, Report Query. If you need access to the report orientation, margins, columns, page sizes, and more, use Report, Report Properties.