On the master page, BIRT supports using autotext report items to add page‑specific values. Some examples include page number, filename, date created, and total page count. The specific autotext item, variable, can be used in conjunction with page scripts to customize page presentation. This autotext element can use either a page variable or a report variable. Page and report variables are created in the Data Explorer view. Page variables are evaluated for every page of a report and report variables are evaluated for the entire report. As an analogy, think of the page n of m autotext item. The n represents the current page number and the m represents the total number of pages. The n variable is analogous to a page‑level variable and the m variable is analogous to the report variable. To support modifying these variables, BIRT provides onPageStart and onPageEnd scripts for the report and any master pages that exist in the report. Using these scripts and variables, a report developer can create reports that have customized headers and footers such as showing sub‑pagination based on groups or phone book style headers that show first and last page entry information.

Use page variables and scripts when using separate run and render tasks, for example when using the BIRT Report Viewer. For example, assume a report is needed that lists customers and the header needs to contain the first and last customer numbers for the specific page. The execution phases and processes are covered in more detail later in this chapter.

To implement this report, the developer creates two page variables, FIRST_CUSTOMER and LAST_CUSTOMER, using the Data Explorer view. Next, the developer adds an OnPageStart event script for the report that sets these variables to null, as shown in Listing 37‑1.

These values are set to null for every new page. Finally, the developer selects the customer number data item and types the onPageBreak script, shown in Listing 37‑2.

The specific customer number and the two page variables are retrieved and then stored in a local JavaScript variable.

This onPageBreak event fires for every instance of this data item that is to appear on the page. Set FIRST_CUSTOMER only once per page. If the first variable is null, the page variable FIRST_CUSTOMER is set to the current customer number. This condition is true only once per page. Next, the LAST_CUSTOMER page variable is set to the current customer number. This setting ensures that the LAST_CUSTOMER page variable is set to the last customer number on the page. The developer then adds two variable autotext report items to the master page header and assigns them the values FIRST_CUSTOMER and LAST_CUSTOMER.

There are three BIRT execution phases: preparation, generation, and presentation. There can be one or two execution processes. When a report runs in the BIRT Report Designer previewer, there is only one execution process, which executes a RunAndRenderTask.

There are two execution processes when the report runs in the viewer. The first process, called the factory process, contains the preparation and generation phases. The second execution process, called the render process, contains only the presentation phase. The render process can occur at a much later time than the factory process and possibly on a different machine.

Because variables are visible only in the process in which they are created, it is important to know which event handlers run in which process. If the render process uses a variable created in the factory process, the code works in the previewer but not at run time if using two processes.