Like hyperlinks, a table of contents provides an effective way for a report user to navigate to specific locations in a large report. A table of contents displays a list of items that reflect the organization of the report. These items are known as table of contents entries. These entries are active links to locations within the report. You can either use the default values for these entries or create custom values that are more meaningful to the report users.
Figure 28‑16 shows a report in the report viewer that displays products by product line. The table of contents, which appears to the left of the report when the TOC button is selected, lists all the product lines in the report. When the user selects a product line, the report viewer displays the corresponding section of the report. When viewing the report in PDF format, the table of contents entries appear as bookmarks to the left of the report.
Figure 28‑16 Report viewer displaying a table of contents next to a report
Using the default table of contents
By default, a grouped report includes a table of contents that displays the group values. For example, if the group key is a data set field named PRODUCTLINE, the table of contents displays all the values in the PRODUCTLINE field, as shown in the example report in Figure 28‑16.
To generate this table of contents, BIRT defines the expression, row["PRODUCTLINE"], in the Table of Contents Item Expression option in the group editor, as shown in Figure 28‑17.
Figure 28‑17 Edit Group displaying the default TOC item expression
BIRT creates a table of contents for every group in a report, not just for the top‑level group. For example, if grouping order data by state, customers, and order ID, the table of contents displays a hierarchy of group values that enable the user to navigate to a particular state, customer, or order ID. To remove a group’s values from the table of contents, simply delete the expression in the Table of Contents Item Expression in the group editor.
Defining a custom table of contents
You can create a table of contents for other report elements, such as dynamic images or data elements. Select the report element from which to use values in the table of contents, choose Table of Contents in Property Editor, then specify an expression that determines the values to display. For example, add a nested table of contents to the report shown in Figure 28‑16 to display product codes under each product line. To create this table of contents, select the [PRODUCTCODE] data element and specify row["PRODUCTCODE"] as the expression for the Table of Contents property, as shown in Figure 28‑18.
Figure 28‑18 Table of Contents property for the selected data element
In the report viewer, the table of contents displays product codes within the product line entries, as shown in Figure 28‑19.
Figure 28‑19 Report viewer displaying a nested table of contents
In some cases, you may not want the table of contents to display field values exactly as they are saved in the data source. For example, the values might be obscure. You can customize the table of contents expression to create a more informative table of contents entry. For example, to display a product name on a separate line after a product code, the table of contents expression would be as follows:
row["PRODUCTCODE"] + " \n" + row["PRODUCTNAME"]
You can provide any valid JavaScript expression as a table of contents expression. For example, to show that a product is obsolete, you can check the value of the OBSOLETE database field, as the following example shows:
if ( row["OBSOLETE"] == "yes" ) {
row["PRODUCTCODE"] + " (Obsolete)"
} else {
row["PRODUCTCODE"] + " \n" + row["PRODUCTNAME"]
}
How to create a table of contents entry
To include a table of contents entry for a report element, type an expression for the Table of Contents property, as shown in Figure 28‑20.
