Define Page Layouts in Word Templates

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 PDF Templates

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.

For example, this element defines a layout with:

<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" />
</layout>

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 Templates.

<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" />
    </layout>
<!-- Define content for your layout here--fixed text and holes as needed -->
</dptemplate>

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');
open(d);

% 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 
moveToNextHole(dp);
append(dp,'My text to fill hole');

% Append this document part to the document
append(d,dp);

close(d);
rptview(d.OutputPath);

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: .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:

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 an 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');
open(rpt);

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';
 
close(rpt);
rptview(rpt.OutputPath);

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.

append(rptObj,paraObj,LayoutObj)

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. = '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';
 
close(rpt);
rptview(rpt.OutputPath);