Home > Articles

This chapter is from the book

Event order sequence

Table 7-6 summarizes which engine task is responsible for a particular phase. The following sections describe the order of event firing for each phase in more detail.

Table 7-6. Engine task by phase

Report engine task

Preparation phase

Generation phase

Presentation phase

RunTask

Yes

Yes

No

RenderTask

No

No

Yes

RunAndRenderTask

Yes

Yes

Yes

Preparation phase operation

The preparation phase includes parameter validation as well as initialization and report element preparation for every element in the report. The preparation phase is identical for all reports. Table 7-7 lists the event types for RunTask and RunAndRenderTask in the order in which the events execute.

Table 7-7. Preparation phase events

Element type and event

RunTask

RunAnd RenderTask

Parameter

getDefaultValueList

Yes

Yes

Parameter

getSelectionValueList

Yes

Yes

Parameter

validate

Yes

Yes

ReportDesign

Initialize

Yes

Yes

ReportItem

onPrepare (iterative)

Yes

Yes

ReportDesign

beforeFactory

Yes

Yes

ReportDesign

beforeRender

No

Yes

The RenderTask does not have a preparation phase. In a RunAndRenderTask, the preparation phase triggers a beforeRender event.

The parameter events fire first for each parameter. Before the parameter entry box is displayed, the getDefaultValueList is called for each parameter. This script returns either a single value or a list of values, depending on the parameter type.

Next, each parameter that provides a list of choices to the user calls the getSelectionValueList. If running reports using the API for RunTask or RunAndRenderTask, the getDefaultValueList script event fires for only parameters that have no value passed. The getSelectionValueList is not called. If using createGetParameterDefinitionTask to build your own parameter entry screen, these events fire much like the example Viewer.

After a user enters values for the parameters, the next event is the validate event, which fires for each parameter. The ReportDesign event, initialize, follows. The initialize event fires once when using only one engine task. Using a separate engine task triggers the initialize event at least two times, one time for the preparation phase, and a second time for the render phase. Additional render tasks or phases also trigger the initialize method.

After the initialize event, the preparation phase triggers the onPrepare event for every element in the report. This process starts with the master page content and proceeds from left to right and top to bottom in the report body. All nested elements process before proceeding to the next element.

The beforeFactory event fires next. This event signals that report creation is about to occur and provides a location for altering a running report.

The beforeRender event fires when using a RunAndRenderTask. When using two tasks, this event does not fire until a render operation occurs.

Generation phase operation

The generation phase includes connecting to data sources, executing data sets and data cubes, evaluating data bindings, and creating all the report items in the report. The data source and data set events fire before the creation of data-bound items, but this processing may not occur before the creation of other report items. For example, if a table is bound to a data set and the report uses a master page with only a label in the footer, the master page content onCreate event fires before the data source and data set events for the data set bound to the table.

This phase triggers the onCreate event for every report item. BIRT processes the report body after processing content on the master page. The report body contains all the report items to be created and rendered. BIRT processes all items at all levels in an iterative fashion, following the same process at each level as it does for the top-level items. A report item that is not contained in another report item is called a top-level report item. BIRT processes the top-level items, going from left to right and proceeding a row at a time toward the bottom right. Every report has at least one top-level report item, usually a grid, list, or table. All nested elements complete OnCreate processing before the next element's onCreate fires.

For each top-level item, BIRT processes all the second-level items before proceeding to the next top-level item. A second-level report item is a report item that is contained within a top-level item. For example, a table contained in a grid is a second-level report item.

There can be any number of levels of report items. To see the level of a particular report item, examine the structure of the report design in Outline, in the BIRT Report Designer, as shown in Figure 7-1.

Figure 7-1

Figure 7-1 Outline showing the level of a report item

If a RunAndRenderTask process executes the generation phase, each element is created and immediately rendered, which fires the onRender event before proceeding to the next element. If a RunTask process executes the generation phase, the onRender events do not fire.

Table 7-8 lists the events triggered in the generation phase for each major report component in the order in which these events execute. The data source, data set, and onPageBreak events are optional.

Table 7-8. Generation phase events

Report component

RunTask

RunAndRenderTask

Master Page content

Data source and data set events (optional)

onCreate

onPageBreak (optional)

Data source and data set events (optional)

onCreate

onRender

onPageBreak (optional)

Body (iterative)

Data source and data set events (optional)

onCreate

onPageBreak (optional)

Data source and data set events (optional)

onCreate

onRender

onPageBreak (optional)

Data source and data set events do not fire if a report item is not data bound or if the report item is bound to another report item that executed previously. The onPageBreak event fires only when an actual page break occurs.

The next three sections describe the data source, data set, data binding, and page break events in more detail.

About data source and data set events

Events for data source and data set elements fire just prior to creating the report item bound to the data set. This sequence occurs for every report item bound to a data set with the exception of the data source beforeOpen and afterOpen events. These events do not fire if a data source has already been used. When a report item is bound to another report item, none of these events fire for the bound report item, supporting two data-bound items sharing one data set without re-executing the data set.

The data source beforeClose and afterClose events fire at the end of the generation phase just before the afterFactory event fires. In the generation phase, there is no difference in data source or data set processing in RunTask and RunAndRenderTask.

BIRT supports data set caching, by which data sets execute only once and are used multiple times. In this case, the data set events fire on only the first use. If a data set is parameterized and the actual parameter value is changed within a report item, the query executes again using the new parameter value. This query execution causes the data set events to fire again. Table 7-9 lists the data source and data set types and events in the order in which these events execute.

Table 7-9. Data source and data set events

Event type and event

RunTask

RunAnd RenderTask

Data source beforeOpen

Yes

Yes

Data source afterOpen

Yes

Yes

Data set beforeOpen

Yes

Yes

DataSet afterOpen

Yes

Yes

DataSet onFetch for all rows of data

Yes

Yes

Process the data-bound Report Item

Yes

Yes

DataSet beforeClose

Yes

Yes

DataSet afterClose

Yes

Yes

About data binding

Data binding in BIRT makes a logical separation between BIRT data sets and data-bound elements, such as tables and lists. Selecting a table or list and then the Binding tab in the Property Editor displays the current bindings for the item. A report developer can create bound columns that use external objects to calculate a specific column value. The bound data set continues to determine the number of rows that are processed for a given table or list.

In a table or list, evaluation of the data bindings for the detail rows occurs before the onCreate event on the current row. This approach supports the onCreate event handler retrieving the appropriate values for the row.

The bindings are evaluated for each detail row in a bound data set. Table footers containing data elements that use a binding are evaluated before the last onCreate event for the final detail row.

Trying to alter a bound column using the onCreate script is discouraged. For example, it is possible to concatenate a column value for a row with all previous rows for the given column using the onCreate script with a JavaScript variable. If this value is in the expression of a bound column, the last value is excluded from the bound column. To display the last value, use a computed column, an aggregation report item, or the dynamic text <VALUE-OF> tag in a text element to display the JavaScript value.

A report developer must not assume any particular evaluation order of binding expressions relative to the various table item events, except that a binding evaluates before the onCreate event of an item that uses it. Best practice is to perform any required manipulation of the data in a data set script or the binding expression.

Data binding evaluation for a group evaluates the bound column many times before creating the table or list item. BIRT performs multiple passes over the data to support grouping. Any script in a group-bound column expression is called every time the data binding evaluates, affecting report performance.

All bindings of a table are always calculated, whether or not these bindings are used by the table. For performance reasons, check the binding list and remove any unused items from the report design.

Report items can share data bindings. For example, two tables can share the same set of bindings. The second table does not re-evaluate the data bindings. To use this feature in the BIRT Report Designer, select the second table, choose Binding in Property Editor, select Report Item, and select the appropriate report item from the list. The list supports only named data-bound report items.

The above scenarios affect any BIRT expression that uses the Available Column Bindings category.

About page break events

Many report items support page breaks. Setting a page break interval on a table instructs the table to process a certain number of rows and then apply a page break. Setting a page break on a group section applies a page break both before and after or only after the group processes. A page break can be applied before many other report items. For example, applying a page break before a row in a table instructs the engine to apply a page break before every row of data that a table processes.

Page events are based on the paginated HTML emitter. If a report generates 5 HTML pages but has 20 PDF pages, the page events fire only 5 times.

The general order of the events is as follows.

  • The engine creates the page.
  • The onPageStart event fires for the report.
  • The onPageStart event fires for the selected master page.
  • For items that are to appear on the page, the onPageBreak event fires.
  • The onPageEnd event fires for the selected master page.
  • The onPageEnd event for the report fires.
  • The engine evaluates the Master Page Auto Text fields.

The onCreate events for all items that are to appear on a page fire before the report's onStart event. Some items have their onCreate triggered but do not appear on a page because of the keep together flag. Such items appear on the following page.

The page-level scripts are used when the Run and Render tasks are separated.

About chart event order

Chart events are handled by the chart engine and execute within the presentation phase. These events are covered in a later chapter.

About table and list event order

The BIRT engine fires the onCreate event for report items iteratively. When processing report items that iterate over data rows, such as a table or list, the event order changes to add additional events for each row of data. Row containers process data rows.

Row execution sequence

Tables, lists, and groups have rows. BIRT processes all rows identically. There are three kinds of rows:

  • Header
  • Detail
  • Footer

Figure 7-2 illustrates the execution sequence for a row. A list or table can contain multiple elements, such as detail rows or table header rows.

Figure 7-2

Figure 7-2 Row execution sequence

Table and list method execution sequence

A list is equivalent to a table that has only a single cell in every row. BIRT processes tables and lists identically, except that for a list, BIRT does not iterate through multiple cells. BIRT processes tables in three steps, the setup, detail, and wrap-up processing steps.

The following sections describe the table and list execution sequence steps.

Table and list setup step

The pre-table processing step is the same for all tables, both grouped and ungrouped.

Figure 7-3 illustrates the execution sequence for the pre-table processing step. This illustration shows the event order when using a RunAndRenderTask in the generation phase.

Figure 7-3

Figure 7-3 Table and list setup execution sequence

A RunTask does not fire onRender events. A RenderTask does not fire onCreate, data source, and data set events. The data source and data set events are optional.

Table and list processing step

The sequence for the table and list processing step depends on whether the table or list is grouped. A table or list having no grouping has a different sequence from one that has grouping.

Figure 7-4 illustrates the execution sequence for a table or list without grouping.

Figure 7-4

Figure 7-4 Ungrouped table or list detail execution sequence

For a table having grouping, BIRT creates one ListingGroup item per group.

A ListingGroup is similar to a table in that it has one or more header rows and one or more footer rows. BIRT processes grouped rows in the same way that it processes a table row.

In addition to the standard onPrepare, onCreate, and onRender events for these rows, the ListingGroup fires the onPageBreak and onPrepare events for the group. To access the script location for these event handlers, locate the group in the outline view and select the script tab. Use code in the onPrepare event handler to modify grouping behavior, such as changing the sort order.

Figure 7-5 illustrates the method execution sequence for a table that has groups.

Figure 7-5

Figure 7-5 Grouped table execution sequence

To verify the execution sequence of event handlers for a specific report, add logging code to the event handlers.

Table and list wrap-up step

The post-table processing step is the same for all tables, both grouped and ungrouped.

Completion of the generation phase

On completion of the generation phase, all data sources, beforeClose and afterClose events fire, followed by the afterFactory event. If using the RunAndRenderTask, the afterRender event fires before closing the data sources. Table 7-10 describes the events available at completion of the generation phase.

Table 7-10. Completing the generation phase

Element type and event

RunTask

RunAndRenderTask

afterRender

No

Yes

Data Source(s) beforeClose

Yes

Yes

Data Source(s) afterClose

Yes

Yes

afterFactory

Yes

No

Presentation phase operation

The presentation phase launches the appropriate emitter and produces report output based on the generated report. This phase fires the onRender events for all items as they are created. If using the RenderTask to render an existing report document, the initialize event triggers first and then each rendered report item's onRender event fires.

If the RenderTask renders pages individually, the onRender event fires only for items that are rendered. For example, BIRT Web Viewer uses a RunTask to create a report document. The web viewer uses a RenderTask to render the first page. This action fires the initialize event first and the onRender event for each item that appears on the page. Selecting a new page and using the pagination controls results in a new RenderTask that calls the initialize event again and triggers the onRender event for each item on the new page.

Event order summary

Table 7-11 summarizes the report design and report item events triggered in each processing phase. The events are listed in the order they are fired for a particular task. Page break, getDefaultValueList, getSelectionValueList, data source, and data set events are not shown for brevity.

Table 7-11. Event order summary

Element type and event

RunTask

RunAnd Render Task

Render Task

Notes

Parameter validate

Yes

Yes

n/a

Only available in JavaScript.

Report initialize

Yes

Yes

Yes

Called multiple times using the RenderTask.

MasterPage Content onPrepare

Yes

Yes

n/a

Body Iterate onPrepare

Yes

Yes

n/a

Report beforeFactory

Yes

Yes

n/a

Data source and data set beforeOpen and afterOpen

Yes

Yes

n/a

Report beforeRender

n/a

Yes

Yes

MasterPage Content onCreate

Yes

Yes

n/a

Body Iterate onCreate

Yes

Yes

n/a

Page Events

Yes

Yes

n/a

Body Iterate onRender

n/a

Yes

Yes

RunAndRenderTask triggers this event immediately after onCreate for a report item.

Report afterRender

n/a

Yes

Yes

Data source and data set beforeClose and afterClose

Yes

Yes

n/a

Report afterFactory

Yes

Yes

n/a

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.

Overview


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information


To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.

Surveys

Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.

Newsletters

If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information


Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.

Security


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.

Children


This site is not directed to children under the age of 13.

Marketing


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information


If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.

Choice/Opt-out


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information


Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents


California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure


Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.

Links


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact


Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice


We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020