Add Bookmarks and a Document Map

• Aug 05, 2024
• 3 minutes to read

This document describes how to use bookmarks for mapping the report elements’ hierarchy to the Document Map that is displayed in a Print Preview, and speeds up the navigation through complex reports.

Tip

Report bookmarks are required to construct a table of contents.

Add Bookmarks to a Report

Do the following to provide bookmarks to your report:

1. Start with a report bound to the CategoryProducts view of the sample Northwind database. See Provide Data to Reports to learn more about data binding.

2. Group the report by the CategoryName field as demonstrated below.

   

3. Select the label placed in the Group Header band and switch to the Properties window’s Expressions tab. Click the XRControl.Bookmark property’s ellipsis button, and in the invoked Expression Editor, select the CategoryName data field.

   

4. In the same way, select the label in the Detail band and bind its XRControl.Bookmark property to the ProductName data field.

   

   Most of the reporting controls (for example, XRTable, XRTableCell, XRCheckBox, etc.) supports the Bookmark property.

5. Set the same label’s XRControl.BookmarkParent property to the label in the group band. This arranges bookmarks into a parent-child structure reflecting the report elements’ hierarchy in the Document Map.

   

   Note

   Avoid cyclic bookmarks that occur when you assign two bookmarks as parents to each other. In this scenario, an exception raises when you attempt to create the report document.

6. Select the report itself and assign text to its XtraReport.Bookmark property to determine the root node’s caption in the Document Map.

   

   The root bookmark displays the report name if you do not specify this property.

Note

Duplicated bookmarks are suppressed to prevent adding multiple bookmarks with the same name to a final document. You can disable the XtraReport.BookmarkDuplicateSuppress property to allow duplicated bookmarks.

The following image illustrates the resulting report with the hierarchical Document Map. Clicking any bookmark navigates the Print Preview to the document section containing the associated element.

Add Bookmarks for Every Page

Do the following to create a document map with bookmarks for each report page:

1. Start with a report bound to the Products table of the sample Northwind database. See Provide Data to Reports to learn more about data binding.

2. Set the report’s XtraReport.Bookmark property to “Table of Contents”.

   

3. Drop the ProductName field from the Field List onto the report’s Detail band.

   

4. Insert a Report Header band by right-clicking anywhere in the report and selecting Insert Band | ReportHeader.

   

5. Drop an XRLabel control onto the Report Header and set its XRControl.Bookmark and XRControl.Text properties to “Home”.

   

6. Add a Page Header band by right-clicking anywhere in the report and choosing Insert Band | PageHeader.

   

7. Drop an XRLabel control onto this band and set the XRControl.Bookmark and XRControl.Text properties to “Page”. Assign the XRControl.BookmarkParent property to the previously created Home label.

   

8. Handle the Page label’s XRControl.PrintOnPage event as follows:

   C#

   using System;
   using DevExpress.XtraReports.UI;
   // ...
   
   private void xrLabel3_PrintOnPage(object sender, PrintOnPageEventArgs e) {
       // Obtain the current page number.
       string s = (e.PageIndex + 1).ToString();
   
       // Change the label's text and bookmark to reflect the page number. 
       ((XRLabel)sender).Bookmark += s;
       ((XRLabel)sender).Text += s;
   }
   

   VB.NET

   Imports System
   Imports DevExpress.XtraReports.UI
   ' ...
   
   Private Sub xrLabel3_PrintOnPage(ByVal sender As Object, _ 
   ByVal e As PrintOnPageEventArgs) Handles xrLabel2.PrintOnPage
       ' Obtain the current page number.
       Dim s As String = (e.PageIndex + 1).ToString()
   
       ' Change the label's text and bookmark to reflect the page number.
       CType(sender, XRLabel).Bookmark += s
       CType(sender, XRLabel).Text += s
   End Sub
   

The image below demonstrates the result.

Initially, the Document Map is exported when you export a report to PDF format. Set the PdfExportOptions.ExportBookmarks property to false to exclude bookmarks from the exported PDF file.