Customize the Page Size and Margins of a Report Programmatically

Open Live Script

This example shows how to use a programmatic approach to customize the page size and the page margins, header, footer, and gutter in a PDF or Microsoft® Word report. Alternatively, you can use a template-based approach. For examples that use the template-based approach, see Customize the Page Size and Margins of a Word Report Using Templates and Customize the Page Size and Margins of a PDF Report Using Templates. Use the template-based approach if you plan to make other modifications to the templates. Otherwise, use the programmatic approach.

By default, the Report API generates pages that have an 11-inch height, 8.5-inch width, and 1-inch margins. Headers and footers are each 0.5 inch wide and the gutter is 0 pixels. You might need to change these dimensions in your report. For example, if you are generating a report for a European locale, you might need to generate A4 pages, which have an 11.69-inch height, 8.27-inch width, and 0.98-inch margins.

To customize the page dimensions of a Report API report programmatically, assign custom mlreportgen.dom.PageSize and mlreportgen.dom.PageMargins objects to the layout object used by the whole report or a report section. The layout object for the whole report is an mlreportgen.report.ReportLayout object, which is assigned to the Layout property of the mlreportgen.report.Report object. The layout for a report section is an mlreportgen.report.ReporterLayout object, which is assigned to the Layout property of the reporter object that represents the section. Objects of these reporter classes have a Layout property that you can use to customize the page dimensions for the section:

mlreportgen.report.TitlePage
mlreportgen.report.TableOfContents
mlreportgen.report.ListOfFigures
mlreportgen.report.ListOfTables
mlreportgen.report.ListOfCaptions
mlreportgen.report.Chapter

If you customize the page dimensions for the whole report and then override the dimensions for a report section, specify all of the properties of the PageSize or PageMargins objects that you create for the section. Otherwise, the properties that you do not specify have default values, which might be different from the values that you specified for the whole report.

In this example, you create a report that has A4 page dimensions and then override those dimensions for the title page.

Create the Report Container

Import the DOM and Report API packages so that you do not have to use long, fully qualified class names.

import mlreportgen.dom.*;
import mlreportgen.report.*;

Create a report container for a Word report. For a PDF report, replace "docx" with "pdf".

rpt = mlreportgen.report.Report("myreport","docx");

Specify Custom Page Dimensions for the Whole Report

Create a PageSize object that specifies an 11.69-inch page height, 8.27-inch page width, and portrait orientation. Assign the PageSize object to the report layout object.

pageSizeObj = PageSize("11.69in","8.27in","portrait");
rpt.Layout.PageSize = pageSizeObj;

Create a PageMargins object that specifies

Top, bottom, left, right margins of 0.98 inches
Header and footer heights of 0.5 inches
Gutter size of 0 inches

pageMarginsObj = PageMargins();
pageMarginsObj.Top = "0.98in";
pageMarginsObj.Bottom = "0.98in";
pageMarginsObj.Left = "0.98in";
pageMarginsObj.Right = "0.98in";
pageMArginsObj.Header = "0.5in";
pageMarginsObj.Footer = "0.5in";
pageMarginsObj.Gutter = "0in";

Assign the PageMargins object to the report layout object.

rpt.Layout.PageMargins = pageMarginsObj;

Override the Page Dimensions for the Title Page Section

Create a title page and specify 2-inch margins, instead of the 0.98 margins specified for the whole report. Specify a 0.5-inch header and footer and a 0-inch gutter.

title = TitlePage("Title","Magic Squares");
title.Subtitle = "Columns, Rows, Diagonals: All Equal Sums";
title.Author = "Albrecht Durer"; 
pageMarginsObj = PageMargins();
pageMarginsObj.Top = "2in";
pageMarginsObj.Bottom = "2in";
pageMarginsObj.Left = "2in";
pageMarginsObj.Right = "2in";
pageMArginsObj.Header = "0.5in";
pageMarginsObj.Footer = "0.5in";
pageMarginsObj.Gutter = "0in";

Assign the PageMargins object to the TitlePage layout object.

title.Layout.PageMargins = pageMarginsObj;
append(rpt,title);

The page size will be the size specified for the whole report because you did not assign a PageSize object to the TitlePage object layout.

Create the Rest of the Report Using the Page Dimensions Specified for the Whole Report

Create the table of contents section. Do not specify a custom page size or custom margins. The page dimensions will be the dimensions specified for the whole report.

toc = TableOfContents;
append(rpt,toc);

Create a chapter that uses the default page dimensions.

chapter = Chapter("Introduction"); 

sec1 = Section("What is a Magic Square?"); 
para = Paragraph(['A magic square is an N-by-N matrix '... 
'constructed from the integers 1 through N^2 '... 
'with equal row, column, and diagonal sums.']); 
append(sec1,para);

append(chapter,sec1);
sec2 = Section("Albrect Durer and the Magic Square"); 
para = Paragraph([ ... 
'The German artist Albrecht Durer (1471-1528) created '... 
'many woodcuts and prints with religious and '... 
'scientific symbolism. One of his most famous works, '... 
'Melancholia I, explores the depressed state of mind '... 
'which opposes inspiration and expression. '... 
'Renaissance astrologers believed that the Jupiter '... 
'magic square (shown in the upper right portion of '... 
'the image) could aid in the cure of melancholy. The '... 
'engraving''s date (1514) can be found in the '... 
'lower row of numbers in the square.']); 
append(sec2,para);
 
append(chapter,sec2);

append(rpt,chapter);

Close and View the Report

close(rpt);
rptview(rpt);