Clarion Community Help

Overview

Using the Report Designer, you visually lay out your application's reports. The Report Designer automatically generates and places all the code structures necessary to produce the reports. Preview the reports without actually generating any code or data.

This topic starts with an overview of Clarion's page oriented print engine, and a comprehensive treatment of each feature of the Report Designer. It concludes with a detailed look at creating a report.

Clarion has many powerful reporting features and we want to systematically cover all of them. However, you the developer, probably have a particular report you need to produce by yesterday! To read about those features that will help you produce your particular report right now, fast forward to the Creating Reports topic in this lesson.

Clarion's Report Engine

Before you explore the Report Designer, it's important to understand how reports are printed by Clarion within the Windows environment. Please refer to How the Print Engine Processes Report Sections at Runtime in the core help file to read an informative topic regarding this process, before continuing to the next section.

Report Designer Interface

Opening the Report Designer

You can access the Report Designer from the Application Generator or from the Text Editor.

To open the Report Designer from the Application Generator

1. From the Application Tree, RIGHT-CLICK the report then choose Report from the popup menu (or press the Report button).

This opens the Report Designer. You're now ready to construct the report, section by section.

When you open the Report Designer with the Application Generator, you have full access to the data dictionary “short cuts”'the Column Toolbox, the Populate menu, the Data / Tables Pad, Control Templates Pad etc.

To open the Report Designer from the Text Editor

1. Open a source code document.

2. Locate a blank line in the data section and place the cursor there.

This is where the Report Designer places the Clarion language REPORT structure.

3. Choose Edit Structure Designer from the IDE menu.

You may also press the CTRL+D keyboard accelerator. This opens the New Structure dialog.

4. From the New Structure dialog, choose a valid Report structure. The following defaults are available:

Paper size A4 - Portrait

Paper size A4 - Landscape

Paper size Legal - Portrait

Paper size Legal - Landscape

Paper size Letter - Landscape

Paper size Letter - Portrait

This opens the Report Designer. You're now ready to define the report.

To edit an existing report from the Text Editor, open the source code file and place the cursor on any line within the REPORT structure, then choose Edit Structure Designer from the menu, or press CTRL+D.

Band View

When you first open the Report Designer, your report appears in Band View. That is, each REPORT section (HEADER, BREAK, DETAIL, FOOTER, and FORM) appears in a separate “band” inside the window. This is true even though the report sections may actually overlap when printed.

Rulers

To quickly determine each section's position, look at the rulers. The horizontal (X axis) ruler shows the position relative to the left edge of the page. The vertical (Y axis) rulers show the positioning relative to the top of each band. The measurement units are set in the Report Properties dialog (see Report Structures and Properties in the Language Reference Manual).

Caption Bars

Each report section has it's own caption bar. Each caption bar displays the band type and an expand/contract button at the far right. Break section caption bars also display the name of the variable the section breaks on.

Show/Hide Button

To expand or contract the report band, click on the expand/contract button at the far right of its caption bar.

Report Designer Toolboxes

During the design process, there are several Report Designer tools at your disposal.

Click on the appropriate link for a more detailed examination of each tool:

In the core help FAQs, examine the following topics:

Using the Report Designer - Sample Reports

Using the Report Designer - Controls Toolbox

Using the Report Designer - Populate Columns

Using the Report Designer - Property Toolbox

Report Designer Alignment Options

Using the Report Designer - Command Toolbar

Report Designer Menus

The Report Designer provides many features available from standard and popup menus.

Please refer to the Report Designer Menu Commands topic in the core help for a detailed explanation of the menu commands and options.

Report Structures and Properties

The REPORT structure contains all the information necessary to format and print each report page. Following is an example of a REPORT structure with empty headers, footer, and form, a break on “CustNumber,” and several variable strings in the detail. The Report Designer generated the following structure.

Report  REPORT,AT(1000,2000,6000,7000),PRE(RPT),FONT('Arial',10,,),THOUS

           HEADER,AT(1000,1000,6000,1000)

           END

CustBreak  BREAK(CUS:CustNumber)

            HEADER,AT(,,,1000)

            END

 Detail     DETAIL

             STRING(@n4),AT(125,52),USE(CUS:CustNumber)

             STRING(@S20),AT(125,208),USE(CUS:Company)

             STRING(@S20),AT(125,365),USE(CUS:Address)

             STRING(@S20),AT(125,531),USE(CUS:City)

             STRING(@S2),AT(125,688),USE(CUS:State)

             STRING(@n5),AT(125,844),USE(CUS:ZipCode)

            END

           END

           FOOTER,AT(1000,9000,6000,1000)

           END

           FORM,AT(1000,1000,6000,9000)

           END

        END

Report Properties

There are two Report Properties dialogs. One of these dialogs is associated with the Report Procedure template. This dialog is accessed with the Report Properties button in the Procedure Properties dialog and is discussed in the Report Template topic.

The other Report Properties dialog is the Report Properties Pad associated with every report, whether or not the Report Procedure template is used. This dialog is accessed from the Report Designer by choosing Report Designer Properties, and discussed here. This dialog allows you to set up basic report options, including page orientation, measurement units, detail print area, fonts and paper size. We recommend setting these options before laying out other parts of your report.

Color

Enter a valid color equate in the TextColor or BackGround fields, or press the ellipsis (…) button to select a color from the Color dialog. The Report Designer adds the COLOR attribute to your report declaration.

See ..\LIBSRC\EQUATES.CLW for a list of valid color equates.

Design

Extra

General

Position

Lets you set the location and size of the report detail print area, by filling in the AT attribute. The measurement units for these boxes are specified on the General tab.

To set a precise starting point for your print detail area relative to the top left corner of the paper, specify Top Left Corner coordinates with this dialog. In effect, this establishes the left margin for your report. The top margin is usually determined by the Page Header position. These settings may also be accomplished visually by dragging report sections and borders in the Report Designer's Page Layout View.

To set the size of the print detail area, choose from the following options for the Width and Height. When changing a report from portrait to landscape, or vice versa, you should also change the width and height on this tab.

Band Properties ' Form

To specify constant text or graphics which print on every page, place it in the FORM. The print engine composes the FORM at the beginning of the print job; it does not update it with each new page. Therefore, the FORM is not suitable for holding variable data, or even a page number. You can, however, print columns from a control table, if you wish to print the same column contents on every page.

The form usually overlaps the other sections and may be used as a layer, to hold graphic frames or “preprinted” material into which the data from the other sections fit. You might use lines and boxes, for example, to divide the DETAIL into compartments, grouping data for the user. You may even create a “greenbar” effect by alternating gray or light green color blocks. Another use for the FORM is to simulate a watermark.

For best results when using a drawing tool to create a watermark, on, for example, a 300 DPI printer, set the fill for the watermark element to 10% gray, or light gray. At higher printing resolutions, try 20% gray.

To add a form to your report, choose Bands Page Form.

For a detailed examination of the Form Band properties, see Report Form Properties in the core help.

Band Properties ' Page Header

To specify text and data to compose at the start of each page, place it in the page HEADER. Remember, the page header may be physically positioned anywhere on the page, not just at the top.

Typically, the HEADER includes a report title and the page number. It is also a useful place to display your company logo. To add a page header to your report, choose Bands Page Header.

For a detailed examination of the Page Header properties, see Page Header Properties in the core help.

Group Breaks

Group breaks provide a means of grouping report data into sections and optionally displaying subheadings, subtotals, or other information associated with the group. Each group consists of a set of row all sharing the same value in the BREAK field.

When the value of the break variable changes, the old group ends and a new group begins. Ending a group means that the last DETAIL in the group is processed and the group FOOTER is composed. Beginning a group means that the group HEADER is composed and the first DETAIL in the new group is processed. In order to produce meaningful groups, the row must be sorted on the same columns the BREAKs are declared on. See Specifying Sort Order and Specifying Nested Group Breaks.

Within a report, you may visually separate these groups with spaces, subtotals, headers, or other summary information, either above the group, below the group, or both. Displaying summary information for a group is accomplished by placing text or graphic controls in a group HEADER or FOOTER.

A BREAK structure may contain most of the same elements as a REPORT structure: group HEADERs, DETAILs, group FOOTERs, and BREAKs. Thus breaks may be nested, giving several levels of record grouping. The Report Designer displays group breaks in an indented outline structure which lets you easily visualize nested group breaks.

For a detailed examination of the Group Break general properties, see Break Properties in the core help.

For a detailed examination of the Group Break Header properties, see Break Group Header Properties in the core help.

For a detailed examination of the Group Break Footer properties, see Break Group Footer Properties in the core help.

Band Properties ' Detail

To specify the data for the body of the report, place it in a DETAIL. This is typically where lowest level information is printed. High level, duplicate, or summary information is better suited to HEADER or FOOTER structures. To add a DETAIL, choose Bands Detail.

Note that a report may have multiple DETAILs that can be printed conditionally. This is useful for printing one-time only pages such as title pages or grand total pages (see Creating Totals and Calculated Fields ). You can also use embedded source statements to control which DETAIL to print at run-time. Each DETAIL structure requires its own PRINT statement.

The DETAIL prints within the print detail area defined by the REPORT's AT attribute. Additionally, any the group HEADERs, group FOOTERs, or group BREAKs also print inside the detail print area.

For best automatic handling when it comes to placing structures on the page, nest your DETAIL inside all other structures. For example, if you have two BREAK structures, one nested in the other, delete all DETAIL structures except the one nested inside the innermost BREAK.

For a detailed examination of the Group Break properties, see Detail Band Properties in the core help.

Band Properties ' Page Footer

To specify text and data to generate at the end of each page, place it in the page FOOTER. Remember, the page footer may be physically positioned anywhere on the page, not just at the bottom. Typically, the page FOOTER includes totals, page numbers, print dates, etc. To add a page footer to your report, choose Bands Page Footer.

For a detailed examination of the Page Footer properties, see Page Footer Properties in the core help.

Next: Lesson 9 - Exploring the Report Procedure