| **Navigation:**  [[welcome to my product .htm|User's Guide and Tutorials]] > The Application >====== Lesson 8 - The Report Designer ====== | [[lesson 7 exploring the form update procedure.htm|{{btn_prev_n.gif|Previous page}}]][[welcome to my product .htm|{{btn_home_n.gif|Return to chapter overview}}]][[lesson 9 exploring the report procedure.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

**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.

{{blk2blue.jpg|blk2blue.jpg}}

**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.

{{tipbox.jpg|TipBox.jpg}}

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 **{{blttria.jpg|BLTTRIA.jpg}}** 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.**

{{tipbox.jpg|TipBox.jpg}}

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** {{blttria.jpg|BLTTRIA.jpg}} **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.

{{repformatter.jpg|repformatter.jpg}}

**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 **{{showhidebut.jpg|ShowHideBut.jpg}}

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 **{{blttria.jpg|BLTTRIA.jpg}}** 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**

| **Locked** | "Freezes" all the controls on the report so that subsequent data dictionary changes are not applied. You can override the #Freeze attribute for all controls or for individual controls. See //Application Options// in the core help.. |

**Extra**

| **Preview** | Specifies the name of a QUEUE which stores the filename(s) (*.WMF) for the metafile(s) generated for page preview. See the PREVIEW attribute in the Language Reference. If you are using the Report Template, it is handled automatically if you check the Print Preview box and you should leave this entry blank. |

**General**

| **Jobname** | Names the print job, as listed in the Windows Print Manager application. |
| **Label** | Type a valid Clarion label to name the REPORT data structure. |
| **Landscape** | Specifies landscape paper orientation. New reports default to portrait mode. Landscape means the report text is aligned parallel with the longest paper edges. |
| **Layout** | Indicates the orientation of the report controls. **Left to Right** maintains the original layout specified in the Report Designer. **Default** field navigation moves from left to right. **Right to Left** essentially "flips" the report controls' display as a mirror image of the layout specified in the Report Designer. |
| **Paper-Type** | Choose from over 40 standard sizes, or choose **//Other//** to specify a custom size. |
| //Width// | Specifies a custom paper width in units specified on the General tab. |
| //Height// | Specifies a custom paper height in units specified on the General tab. |
| **Prefix** | Specifies the label prefix for the REPORT structure. |
| **Text****Font** | To set the default font// //for all controls appearing in the report, press the **Font **button, then choose the font and style in the Font dialog. You may override the default by setting a different font in the Properties dialog for any specific control. The options you choose in the dialog become the parameters for the FONT attribute. As you choose options, the dialog box displays a sample of the formatting. |
| **Units** | Specifies the default measurement for all controls placed in the report. Choose **Dialog **Units, **THOUS**andths of Inches, **M**illi**M**eters or **POINTS**. |

**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.

| **Default** | Sets a value based on the Paper **Type** property. |
| **Value** | To set a specific size, mark the **Value **choices. |

__**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.

{{tipbox.jpg|TipBox.jpg}}

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 {{blttria.jpg|BLTTRIA.jpg}} 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 {{blttria.jpg|BLTTRIA.jpg}} 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 [[lesson 9 exploring the report procedure.htm#specifying sort order|Specifying Sort Order]] and [[lesson 9 exploring the report procedure.htm#specifying nested group breaks|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 {{blttria.jpg|BLTTRIA.jpg}} 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 [[lesson 9 exploring the report procedure.htm#creating totals and calculated columns|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.

{{tipbox.jpg|TipBox.jpg}}

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 {{blttria.jpg|BLTTRIA.jpg}} 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.htm|Lesson 9 - Exploring the Report Procedure]]