Reporting

Pagination refers to the number of pages within a report and how report items are arranged on these pages. Pagination varies depending on the used renderer, page break and keep-together options you configure the report to use.

A successfully designed report that is optimized for the renderer that you plan to use to deliver your report, requires understanding of the rules used to control pagination.

This topic discusses the impact of the physical page size and the report layout on how page break renderers render the report.

Page Setup

When you render a report you can specify page setup options at run-time or design-time. Some of these options can be changed by the user using the Page Setup dialog. Page setup options apply to all report output types.

Page Settings

The PageSettings property of the Report object allows you to customize the following properties:

PropertyDescription
LandscapeTrue to print in landscape orientation, False to print in portrait orientation.
MarginsA Telerik.Reporting.Drawing.MarginsU object, which lets you individually specify the margins at the four sides of the report.
PaperKindThe type of paper to print the report on, such as Letter, Legal, A3, or A4. Setting this automatically sets the correct dimensions in the PaperSize property.
PaperSizeIf the Paper Kind is "Custom" you can specify a non-standard set of paper dimensions.
WatermarksTypically used to designate a document's status e.g. draft or for internal distribution only. They are commingled with the report content, making them next to impossible to ignore.

Physical Page

The physical page size is the paper size. The paper size that you specify for the report controls how the report is rendered. Reports rendered in physical page formats insert page breaks horizontally and vertically based on the physical page size to provide an optimized reading experience when printed or viewed in a physical page format. Reports rendered in logical page formats insert page breaks horizontally based on the physical size to provide an optimized reading experience when viewed in a Web browser.

You can change page size by changing the PaperSize.Height and PaperSize.Width properties in the Properties pane. The page size does not grow or shrink to accommodate the contents of the report. If you want the report to appear on a single page, the whole report content must fit on the physical page. If it does not fit and you use physical page format, the report will occupy additional pages. If the report grows past the right edge of the physical page, then a page break is inserted horizontally. If the report body grows past the bottom edge of the physical page, then a page break is inserted vertically.

Margins

Margins are specified by changing the Top, Bottom, Left and Right properties in the Properties pane. The area of the physical page that remains after space is allocated for margins, column spacing (multi-column), and the page header and footer, is referred to as usable page area. Margins are only applied when you render and print reports in physical page formats.

Multi-columns (Newsletter-Style Columns)

When a report is divided into multiple columns, physical pages are divided vertically into columns, each of which is considered a logical page. Suppose you have two columns on a physical page - the content of your report fills the first column and then the second column. If the report does not fit entirely within the first two columns, the report fills the first column and then the second column on the next page. Columns continue to be filled, from left to right, top to bottom until all report items are rendered. For more information, see How to: Create a Multi-Column Report.

Paging and Keep Together

Based on report content and page settings the report is divided into one or more pages. The actual report content is rendered on a page after margins are subtracted from the page size.

If the report body cannot fit in the available page width, a new page will be added in order to accommodate all content. At design-time, a vertical red line will appear to indicate the available width. Make sure report sections and items do not cross this boundary if you do not want them to be split across different pages.

Caution

If every other page in a report seems to be blank, the most probable reason is that a report item is stretching over the right page margin (appears over the vertical red line in report designer) and in case it has no background or border, you will not be able to detect it, but it is still there and is causing a new page to be created.

In the vertical direction, by default sections are not split across different pages, unless their KeepTogether property is set to false. If you want to force a page break before or after a section, use the section’s PageBreak property.

Simple report items (i.e. non-container items) are always kept together on a page if possible. If not, they are rendered at the beginning of the next page. If they still cannot fit, because they are longer than a whole page, they are split. The PictureBox, Shape and Chart items are always kept together.

By default groups are not kept together on a single page. You can instruct the rendering engine to try to keep the entire group or the group header with the first detail on a single page if possible by setting the GroupKeepTogether property of the Group component.

Note

If the content that should be kept together is too large to fit on a single page, it is not moved and is left on the current page, forcing the rest of the content to move to next page, as if KeepTogether is false.

Example: Report group has GroupKeepTogether=FirstDetail, this means that the summary height of the group header, height of all child group headers (if any) and height of the first detail should be able to fit on a single page in order for the KeepTogether algorithm to work and move the whole Group on a new page.

Horizontal Paging

If the report spans over several pages in width then its sections are stretched from the left edge of the left-most page’s printable area to the right edge of the right-most page’s printable area, as displayed in the following diagram:

Caution
If your report item (table) is too wide to fit on the page it will cause a horizontal overflow and will continue on the next page. However whenever this happens if there is additional content below the table a blank page for each additional page (needed by the table) will be generated. To understand this better consider the following example:

page 1 (first part of table)

page 2 (second part)

page 3 (third part)

page 4 (another content here)

page 5 (empty)

page 6 (empty)

Report sections

Report sections can shrink to accommodate the report items contained within. They do not reflect the physical page size and can grow beyond the boundaries of the physical page size to span multiple report pages. Some renderers, such as HTML and MHTML render reports that grow or shrink depending on the contents of the page. Reports rendered in these formats are optimized for screen-based viewing in a Web browser. These renderers add vertical page breaks when required.

See Also