Rave: The Report Authoring Visual Environment

To start the Rave visual report design environment, double-click on a TRvProject component dropped on a form or select Tools ® Rave Designer in the Delphi IDE. When you activate this environment, you'll see a window like that shown in Figure 18.1. As you can see, the Rave Designer includes several sections: the Page Designer, Event Editor, Property panel, Project Tree panel, toolbars, Toolbar Palette, and status bar.

Figure 18.1: The Rave Designer with a simple report

Keep in mind that Rave allows your end users to create or modify their own reports. You can set the Rave Designer level to Beginner, Intermediate, or Advanced in the Edit ® Preferences dialog box (in the Environment section) so your end users will be working at the level they're comfortable with and won't have more power than you want to give them. You can also lock features of the report so they cannot be modified.

Using the RvProject Component

Figure 18.1 shows a trivial Rave report, which is stored in a .rav file. To connect this report to your Delphi 7 application you use the Rave page, which provides a series of components. The central component is RvProject. Place this component on a form or data module, set its ProjectFile property to a Rave file, and write this event handler code for a button:

RvProject1.Execute;

You now have a working application (the RavePrint example among the source code files) that can print a report and that includes an embedded print preview feature, as you can see in Figure 18.2. The referenced file should be distributed separately, and can be modified without having to change the Delphi program. As an alternative, you can also embed the .rav file into the Delphi executable by loading it in the DFM file. To accomplish this, use the StoreRAV property of the Rave project component.

Figure 18.2: The Rave Report Preview window for a report

To control the most important settings of the report and the preview, you can hook an RvNDRWriter or an RvSystem component to the Engine property of the RvProject component:

RvNDRWriter Component  Generates an NDR formatted file when the report is executed. NDR formatted files are of a proprietary binary format and store all information needed by the rendering components to reproduce the report in a wide variety of formats.

RvSystem Component  Combines the RvNDRWriter component with a standard print, preview, and rendering user interface. Many properties are available to customize the user interface, and override events can be defined to replace the standard dialogs with custom versions.

Rendering Formats

The Rave engine produces an NDR file or stream, generated by the RvNDRWriter. Rave's rendering engine can convert this internal representation to a wide variety of formats. To let a user choose one of the target file formats, drop the desired render components within a form of your Delphi program. When running the RvProject component's Execute method (as in the RavePrint example), you can choose one of the file formats in the dialog box displayed by Rave and visible in Figure 18.3.

Figure 18.3: After executing a Rave project, a user can choose the output format or rendering engine.

These are the available rendering components on the Rave page of Delphi's Component Palette:

RvRenderPreview  Can be used to display an NDR file or stream to the screen. A ScrollBox component is used to display the report pages, and many methods and properties are available to create custom preview dialogs. Unless you need a custom print preview, you should use the RvSystem component for previewing instead of RvRenderPreview.

RvRenderPrinter  Sends an NDR file or stream to the printer. Unless you need a custom printing or previewing interface, you do not need to use this component—RvSystem provides standard printing functionality.

RvRenderPDF  Converts an NDR file or stream to PDF (Adobe Acrobat) form. You can use properties and events to customize the type of output that is created and to provide compression support.

RvRenderHTML  Converts an NDR file or stream to HTML (DHTML) form. Each page is rendered to a separate page and can be combined with templates for greater output control.

RvRenderRTF  Converts an NDR file or stream to RTF form. The RTF format uses field areas for accurate positioning and reproduction of the report.

RvRenderText  Converts an NDR file or stream to text form. Many graphical commands and components, such as lines and rectangles, are ignored during text rendering.

In addition to letting a user choose a file format in the dialog, rendering can be done programmatically. For example, to convert a report to a PDF file directly, you can write the following code (taken again from the RavePrint example):

procedure TFormRave.btnPdfClick(Sender: TObject);
begin
  RvSystem1.DefaultDest := rdFile;
  RvSystem1.DoNativeOutput := False;
  RvSystem1.RenderObject := RvRenderPDF1;
  RvSystem1.OutputFileName := 'Simple2.pdf';
  RvSystem1.SystemSetups := RvSystem1.SystemSetups - [ssAllowSetup];
  RvProject1.Engine := RvSystem1;
  RvProject1.Execute;
end;

Data Connections

Data connection components provide a link between data contained in a Delphi application and the DirectDataViews available in the Rave Designer. Notice that the value defined in the Name property for each data connection component is used to provide the link with the Rave report. For this reason, take care to avoid changing the component names after the DirectDataViews are created in Rave.

The data connection components are as follows:

RvCustomConnection  Provides data to Rave reports using programmed events and can be used to send non-database data to a visual report.

RvDataSetConnection  Connects any TDataSet class descendent component to a Rave DirectDataView. Using the FieldAliasList property, you can also modify the names of the dataset fields, replacing them with more legible names for the developers or end users building the report. If you need sorting or filtering for lookups or master-detail relationships within the Rave reports, you can handle the OnSetSort and OnSetFilter events.

RvTableConnection and RvQueryConnection  Connect BDE Table and Query components to a Rave DirectDataView. Rave natively provides sorting and filtering support for table connections.

As a first example of how to construct a database-related report, I've created the RaveSingle example, which is an update of the DbxSingle program (built in Chapter 14, "Client/ Server with dbExpress") with a Rave project and a connection:

object RvDataSetConnection1: TRvDataSetConnection
  RuntimeVisibility = rtDeveloper
  DataSet = SimpleDataSet1
end
object RvProject1: TRvProject
  ProjectFile = 'RaveSingle.rav'
end

In the Rave Designer, I created a new project, the file RaveSingle.rav in the RaveSingle folder. To refer to the data exposed by the Delphi program, you need to add a data view by clicking the New Data Object button on the Project toolbar, selecting the Direct Data View option (more details on the other alternatives later), and choosing an available connection. The list you'll see depends on the connections available in the project currently active in the Delphi IDE.

You can now create a report with the help of a wizard. From the Rave Designer menu, choose Tools ® Report Wizards ® Simple Table. Select the data view (you should have only one if you've followed these steps), and in the following window choose the dataset fields you want to include in your report. You should see a report like the one shown in Figure 18.4.

Figure 18.4: The RaveSingle report (generated with the help of a wizard) at design time

As you can see the in the Project Tree, the wizard generated a report page with a Region containing three Band components: one for the title, one for the table header, and a data-aware band for the items. I'll cover the details of using these components in the section "Regions and Bands," later in this chapter; for the moment, I wanted to build and let you experiment with a working example.