Create Page Layout Sections

You can add sections to a report using the class. This predefined class automatically adds a formatted section into your report. The default formatting is portrait orientation with a default margins and a page number in the footer. You can override the layout and contents of the section. It is much easier and more efficient to use this class rather than using DOM objects to create a section. For information and examples, see

You can also use DOM objects to create sections. You can divide a Word or PDF document into sections, each with its own page layout. Page layout includes page margins, page orientation, and headers and footers.

Define Page Layouts in a Word Template

Every Word template has at least one page layout section. You can use Word to create as many additional sections as you need. For example, in the main template for a report, you can create sections for your report’s title page, table of contents, and chapters. See the Word documentation for information on how to create page layout sections in a Word template.

Define Page Layouts in a PDF Template

You define page layouts in a PDF template using a <layout> element. You can use the <layout> element in the main template (root.html), and in document part templates.

You can use these attributes with the <layout> element.


page-margin: top left bottom right header footer gutter; page-size: height width orientation

first-page-numberNumber of first page in the layout
page-number-format n or N for numeric, a, A, i, I
section-breakWhere to start section for this layout: Odd Page, Even Page, or Next Page

For example, this element defines a layout with:

  • Top, bottom, left, and right margins of 1 inch

  • Header and footer heights of 0.5 inches

  • Gutter size (space for binding pages) of 0

  • 8.5-inch by 11-inch page size in portrait orientation

<layout style="page-margin: 1in 1in 1in 1in 0.5in 0.5in 0in; 
        page-size: 8.5in 11in portrait" />

This <layout> element includes a page footer. The page footer DefaultPageFooter must be defined in a document part template.

<layout style="page-margin: 1in 1in 1in 1in 0.5in 0.5in 0in; 
        page-size: 8.5in 11in portrait">
        <pfooter type="default" template-name="DefaultPageFooter" />

You can create page layouts in document parts. For example, this code defines a document part template named Chapter that includes a page layout. The layout includes a page header and a page footer and specifies the format for the page number using the <pnumber> element. In this case, also define part templates for the page header and page footer elements. See Use Page Headers and Footers in a Template.

<dptemplate name="Chapter">
    <layout style="page-margin: 1in 1in 1in 1in 0.5in 0.5in 0in; 
						page-size: 8.5in 11in portrait">
          <pheader type="default" template-name="MyPageHeader"/>
          <pfooter type="default" template-name="MyPageFooter"/>
          <pnumber format="1" />
<!-- Define content for your layout here--fixed text and holes as needed -->

To use the layout, insert the document part into your report using your program. This code assumes that there is one hole in the document part Chapter. The document part uses the page layout definition you provided in the Chapter document part template.

import mlreportgen.dom.*
d = Document('myDocPartEx','pdf','mytemplate');

% Assign the Chapter document part template to the variable dp
dp = DocumentPart(d,'Chapter');

% Move to each hole in this document part and append content 
append(dp,'My text to fill hole');

% Append this document part to the document


Watermarks in PDF Page Layouts

You can place a watermark in a PDF page layout. A watermark is an image that appears in the background of a page, such as the word Draft or Confidential. It runs behind the text on each page you apply it to. You can use any of these file types for the image: .bmp, .jpg, .pdf, .png, .svg, and .tiff.

Use <watermark> in a <layout> element. Specify the watermark as an image file stored in the template package. To store the image in the template package, unzip the template package, copy the image into the folder, and then zip the template again. For example:

  1. Unzip the template.

  2. Copy the watermark image into the folder MyTemplate. To keep your images organized, copy the image into the images folder.

  3. Add the watermark element to a page layout in your template. For example, add the watermark to the default layout in root.html.

    <layout style="page-margin: 1in 1in 1in 1in 0.5in 0.5in 0in; 
           page-size: 8.5in 11in portrait" >
      <watermark src="./images/myfile.png" width="6in" />
  4. Zip the template.

  5. Delete the folder MyTemplate.

  6. Create a report that uses this template using the DOM API, or create a form-based report in Report Explorer whose PDF Page Layout component uses this layout.

Navigate Template-Defined Page Layouts

A document or document part’s CurrentPageLayout property points to a page layout object that specifies the current section’s page layout based on the document or document part’s template. Each time you move to a new section (by moving to a hole at the beginning of the section), the DOM updates the CurrentPageLayout property to point to the page layout object that specifies the section’s page layout properties. You can change a section’s page layout by modifying the properties of the layout object or replacing the layout object with a new object.

For example, you can change the section’s orientation or add page headers or footers. Make these changes before you add any content to the new section. When replacing the current layout object, use a mlreportgen.dom.DOCXPageLayout object for Word documents and mlreportgen.dom.PDFPageLayout for PDF documents.

Override Template Page Layouts in Your Report Program

You can change the template-defined layout properties programmatically. For example, the page orientation of the DOM default Word template is portrait. This example changes the orientation to landscape to accommodate wide tables. The code swaps the height and width of the page to the new page orientation.

import mlreportgen.dom.*
rpt = Document('test','docx');

sect = rpt.CurrentPageLayout;
pageSize = sect.PageSize;
pageSize.Orientation = 'landscape';
saveHeight = pageSize.Height;
pageSize.Height = pageSize.Width;
pageSize.Width = saveHeight;
table = append(rpt,magic(22));
table.Border = 'solid';
table.ColSep = 'solid';
table.RowSep = 'solid';

Create Layouts Programmatically

You can append a DOCXPageLayout object (for Word documents) or a PDFPageLayout object (for PDF documents) to start a new page layout section programmatically. For DOCX reports, the append method can specify a paragraph to end the previous section.


If you do not specify a paragraph in your append method, the DOM API inserts an empty paragraph before starting the new section. This example uses the end paragraph syntax to avoid inserting an empty paragraph at the end of the previous section.

import mlreportgen.dom.*
rpt = Document('test','docx');

append(rpt,Heading(1,'Magic Square Report','Heading 1'));

sect = DOCXPageLayout;
sect.PageSize.Orientation = 'landscape';
sect.PageSize.Height = '8.5in';
sect.PageSize.Width = '11in';
append(rpt,Paragraph('The next page shows a magic square.'),sect);
table = append(rpt,magic(22));
table.Border = 'solid';
table.ColSep = 'solid';
table.RowSep = 'solid';

See Also


Related Topics