Internally the classic engine uses a set of report-states to process a report. Each report state captures all variables and object states of a particular process state. The report processing always starts with a BeginReport-State and ends with a ReportFinishedState. Each state is independent and allows to suspend and restart the report processing at a later time.
Understanding the report-state and its state-transitions is crucial to understand how the reporting engine processes the data and generates the events that drive the report content generation. Some events can spawn subreport processes if the corresponding root-level band contains subreports as childs.
Banded report processing
BeginReport
The BeginReport state initializes the report processing, queries the data and activates all functions for the report. The state fires the report-initialized event to all functions to inform the functions that a new report processing run has started.
Previous states | |
Next state | ReportHeader |
Event | reportInitialized(..) |
Subreports |
ReportHeader
The report header state is responsible for printing the report header. The state fires the report-started event to all functions.
If the first group of the report is a crosstab-group, this state transitions into a BeginCrosstabState next, otherwise it continues as BeginGroup state.
Previous states | BeginReport |
Next state | BeginGroup, BeginCrosstab |
Event | reportStarted(..) |
SubReports | on ReportHeader |
BeginGroup
Activates a group. Every report is guaranteed to have at least one group. A group is defined as "consecutive set of rows, which have the same values in the columns specified by the group's arguments". Groups are formed by specifying grouping arguments; usually the name of one or more columns; that control which rows contain into a given group instance. Groups can be nested into each other. On nested groups, each subgroup automatically inherits the grouping arguments of their parent groups. Therefore a group is considered finished if either the values of the group arguments change or if one of the parent groups is finished.
If the current group of the state is not the inner most group, the state will transition into another BeginGroup-state. If the next group is a crosstab-group, the state continues with a BeginCrosstab-state. Once all groups are opened, the processing continues with the BeginDetails-state.
Previous states | ReportHeader, BeginGroup, JoinEndGroup |
Next state | BeginGroup, BeginDetails, BeginCrosstab |
Event | groupStarted(..) |
SubReports | on GroupHeader |
BeginDetails
This state starts the details-processing. During the processing, the layouter will print the details-headers and prepares the details-footers. If the main datasource of the report is empty, this state will trigger the printing of the no-data-band.
If the main datasource is empty, this state transitions into a EndDetailsState immediately.
Previous states | BeginGroup |
Next state | ProcessDetails, EndDetails |
Event | itemsStarted(..) |
SubReports | on NoDataBand if the data-source is empty |
ProcessDetails
This state processes the itemband. The reporting engine's state processing generates a process-details state for each row in the report's data-source. If the data-source is empty, no such state is generated. Therefore reports with no rows in the report's datasource will generate all group-headers and footers but will not produce any itembands.
Previous states | BeginDetails |
Next state | JoinDetails |
Event | itemsAdvanced(..) |
SubReports | on ItemBand |
JoinDetails
This state post processes the itemband. If the current group is not finished, it advances the internal cursor to the next row of data, otherwise it delays the advance operation until all group-footers have been printed.
This state is an artificial state and therefore it generates no events. If the current group is not finished, this state transitions into a new ProcessDetails-state, otherwise the details section is finished by transitioning into a EndDetails-state.
Previous states | ProcessDetails |
Next state | ProcessDetails, EndDetails |
Event | |
SubReports |
EndDetails
The EndDetails state signals the end of the details section processing and triggers the printing of the details-footer.
Previous states | BeginDetails, JoinDetails |
Next state | EndGroup |
Event | itemsFinished(..) |
SubReports |
EndGroup
The EndGroup state finishes the current group. It triggers the printing of the group-footer and closes the group's instance. This state unconditionally transitions into a JoinEndGroup state.
Previous states | EndDetails, JoinEndGroup, JoinCrosstab |
Next state | JoinEndGroup |
Event | groupFinished(..) |
SubReports | on GroupFooter |
JoinEndGroup
This is another artificial state to simply the report processing. If the report has reached the end of the data-source or if the parent group is finished as well, this state transitions into a new EndGroup state to finish the parent group. Otherwise, if the report contains more data, this state continues as BeginGroup state.
Previous states | EndGroup |
Next state | ReportFooter, EndGroup, BeginGroup |
Event | |
SubReports |
ReportFooter
This state fires the reportFinished event to inform all functions that the report processing is going to end soon. This also triggers the printing of the report footer.
Previous states | JoinEndGroup |
Next state | EndGroup, BeginGroup, BeginCrosstab |
Event | reportFinished |
SubReports | on ReportFooter |
ReportDone
This state fires the reportDone event, which is a global signal for all functions to clean up their internal state as the reporting ends now. Depending on whether the current report is a master report or a subreport, this state transitions into either a EndReport or EndSubreport state.
In the old days, this event was used to postprocess the report footer for the final printing, but as of 0.8.9 this part of the event processing is disabled and has no effect in the current layouting system.
Previous states | ReportFooter |
Next state | EndReport, EndSubReport |
Event | reportDone |
SubReports |
EndSubReport
This state merges the subreport processing with the parent report-state. The state will transform into a copy of the stored parent state to continue the report processing where the subreport process interrupted it.
Previous states | ReportDone |
Next state | any state able to spawn subreports |
Event | |
SubReports |
EndReport
This state is a artificial state to allow the report processor to detect that the report processing has finished. The state does nothing and any attempt to advance the state into something else will produce errors.
Previous states | ReportDone |
Next state | |
Event | |
SubReports |
Crosstab report processing
