Step 15) Custom Reports

Prerequisites
Introduction
Important Concepts
Learning Resources

Prerequisites

Introduction

One of the most important tasks a database can perform is printing reports. 4th Dimension provides several different mechanisms for printing reports that provide various capabilities.

One of the most important tasks in data management is report generation. The Quick Report editor is one of two tools used in 4th Dimension to design reports. You use the Quick Report editor to create ad-hoc reports in the User environment. The other tool is the Form editor, which you can use to design complex reports in the Design environment which go beyond the capabilities of the Quick Report editor. Reports created with the Form editor use output forms to allow you to create complex designs, programmatic processing, or include graphics.

With the Quick Report editor, you can:

Produce lists of records
Create break areas
Produce cross-tab reports
Computer summary calculations
Use fonts and styles in the report
Define borders and background colors on a cell basis
Save and open quick report designs to disk
Select different output types such as HTML, text file, 4D View area, chart or print to disk

More information about the Quick Report editor can be found in the 4D 2003 Quick Report Reference manual (PDF).

Using the Form editor to design your reports allows you tremendous flexibility in the creation of custom reports.

With the Form editor, you can:

Use the Form wizard to assist in creating attractive columnar reports
Print one record per page
Intelligent handling of subforms, pictures, and text fields depending on the data contained in those objects
Print side-by-side text fields which automatically adjust their height depending on the amount of text contained in each one
Print custom mailing labels which can include graphic elements, any available font and even variables
Create simple mail-merge documents
Completely control break processing and placement of print control lines
Execute methods during printing to control the content and appearance of printed reports

More information about creating reports using the Form editor, see 4D Design Reference (PDF), Chapter 6, pages 451 – 476

Important Concepts

Control lines (aka Markers)

All form editor reports use the control lines to designate the bottom of an area on the form. By default, there are four control lines that appear on every form. They’re used to control the spacing different parts of the form for display on output forms, and for printing custom reports:

H (Header): Printed once at the top of each page
D (Detail area): Printed once for each record in the selection
B0 (Break level 0): Printed once at the end of the report
F (Footer): Printed once at the bottom of each page

You can have additional Break areas and additional Break Header areas.
Although control lines appear on forms used for input, they are not used.
When printing reports created with the Form editor, there are two mechanisms that can be used to manage the generation of reports: Print Selection and Print form.

Print Selection

The first mechanism uses the command PRINT SELECTION, and performs the same action as the Print menu command in the User environment. The PRINT SELECTION command prints the current selection of the table passed to the command. If the selection is empty, PRINT SELECTION does nothing.

Example

PRINT SELECTION([Contacts])

By default, PRINT SELECTION displays the printer dialog boxes (print settings and page setup) before printing. If the user cancels out of either of the printer dialog boxes, the command is canceled and the report is not printed.

You can suppress these dialog boxes by using either the optional asterisk (*) parameter which will cause the print job to use the current print parameters as defined by the PAGE SETUP command and/or the SET PRINT OPTION command, or the optional “greater than” (>) parameter which will cause a print job without reinitializing the current print parameters.

During printing, the output form method and/or the form’s object methods are executed depending on events that are enabled in the Form and Object Properties windows in the Design environment, as well as the events actually occurring:

An On Header event is generated just before a header area is printed
An On Printing Detail event is generated just before a record is printed
An On Printing Break event is generated just before a break area is printed
An On Printing Footer event is generated just before footer is printed

This gives you the opportunity to perform additional processing depending on your specific requirements.

Objects whose contents are dynamic in nature, such as included forms and text fields and variables, can be set to resize dynamically based on the size of their contents.

More information on the PRINT SELECTION command.

More information on the PAGE SETUP command.

More information on the SET PRINT OPTION command.

Print Record

The PRINT RECORD command prints the current record of the specified table, without modifying the current selection. Like PRINT SELECTION, the current output form is used for printing. If there is no current record, PRINT RECORD does nothing. The only difference between PRINT RECORD and PRINT SELECTION, as their names imply, is that one prints only the current record, and one prints the current selection.
You can print subforms and external objects with the PRINT RECORD command. This is not possible with the Print form command (discussed next).

Just like PRINT SELECTION, by default PRINT RECORD displays the printer dialog boxes before printing. The same options are available for suppressing these dialog boxes.

PRINT RECORD is useful for when you want to print an invoice for the current record within the current selection without changing the current record (or current selection).

More information on the PRINT RECORD command.

Print form

The Print form command is used for very complex reports that require complete control over the printing process. Print form does not do any record processing, break processing, or page breaks. These operations are the responsibility of you, the developer.

Since Print form does not issue a page break after printing the form, it is easy to combine different forms on the same page. Thus, Print form is perfect for complex reporting tasks that involve different tables and different forms. To force a page break between forms, use the PAGE BREAK command. To carry printing over to the next page for a form whose height is greater than the available space, call the CANCEL command before the PAGE BREAK command.

The Print form command supports three different syntaxes:

Detail area printing: Print form only prints the Detail area (the area between the Header line and the Detail line of the form.
Form area printing: Print form will only print the section designated by the marker constants passed as the third parameter.
Section printing: Print form will print the section included between the two numeric values passed to the command as the third and fourth parameters. These values correspond to the vertical position on the form expressed in pixels.

Subforms and external objects are not printed with Print form. To print only one form with these types of objects, use PRINT RECORD instead.

More information on the Print form command.

Learning Resources

Modifying Output Forms for Reports
4D Design Reference (PDF)
Chapter 6, page 451
Discusses Printed Columnar reports, one record per page reports, using subforms, reports with a text field, custom mailing labels, creating mail-merge documents.

Basic Steps for Creating a Printed Report
4D Design Reference (PDF)
Chapter 6, page 457
Walkthrough of the process to create a report using the Form editor, including creating a report with breaks; creating additional control lines; initializing break processing; reports with subtotals; summary reports; including date, time, and page number data in reports; printing subforms, pictures, and text fields; picture field formatting options; and printing labels.

Form Reports
4D User Reference (PDF)
Chapter 7, page 127
Brief discussion of printing Form reports from the User environment.

Quick Report Editor (QuickTime movie)
Walkthrough of the various capabilities of the new Quick Report Editor.

4th Dimension 2003 Quick Report Editor Reference Manual (PDF)
Complete discussion of all features in the new Quick Report editor, including using the Quick Report wizard; List reports cross-tab reports, working with the editor; setting borders; sorting records, adding summary calculations; setting display formats; hiding and showing rows and columns; adding page headers and footers; generating reports to the printer, disk files, graphs, 4D View, and HTML. Includes a complete description of the new commands added to the language to support developer-defined custom report interfaces.

Commands and Topics for Printing
Complete description of all language commands available for printing custom reports.