Thursday, 30 August 2007

FreshReports: elements and sections

In FreshReports, an element is a minimal unit of printed information. Typical elements are text strings and geometry shapes. Elements are organized into sections. A section is a container for elements; each element belongs to one and only one section. A section can provide logical grouping, positioning (for example, a page header section) and, most important, data. A section can have a data source and thus serve as a data provider to its elements.

Most readers are familiar with traditional reporting components, starting with MS Access reports. Using this analogy, our sections correspond to traditional details and group/report headers/footers. However, in traditional reporting we typically have database rows pulled by some inner join query, so the data is essentially flat. FreshReports, on the other hand, uses object graphs as data, so we can have tree-like structure of sections inside other sections.

FreshReports have a notion of "design time" or "template" section. This is essentially the section definition. Think of it as object representation of the section definition you see in the designer. At runtime, it generates one or several identical clones, named "runtime sections" (or sometimes "detail sections"), according to its data source. This data source corresponds to a table or query result in the traditional reporting scenario, while the DataItem property corresponds to a database row. Individual elements display properties of the DataItem. Note that an element can display several property values mixed with text (the syntax is very close to that of MS Access).

Sections can be broken between pages in 3 different ways, according to the KeepTogether property. The first way is no limitation. If some elements don't fit on this page, they go to the next. At this point, it's not very useful: these elements are going to be printed not at the top of the page but at the same shift from the top of the section. But anyway a typical section is a row of elements, so they won't break to the next page. A more useful scenario is when a section contains some elements and another section. But anyway this is going to work properly only when I implement pushing -- this is when some elements "push" others when they grow.

The second possibility is to keep each runtime section together. And the last is to keep the whole section (all its clones) on one page.

At some point it's going to turn into a set of customizable rules (for example, you'll be able to keep several sections on one page -- useful for table headers).

Note that the features described here are scheduled for the 0.5.1 release.

No comments: