Create Page Footers and Headers

You can create page headers and page footers in Word and PDF reports. You can create page headers and page footers in each layout for each of these types of pages:

  • The first page of the section

  • Even pages

  • Odd pages, which include the first page if you do not specify a first-page header or footer

You can create report page headers and footers programmatically or in the template to use with the report. You can append content to the footers.

When you open a report, the DOM API:

  1. Reads the headers and footers from the template and converts them to PDF or DOCX PageHeader and PageFooter objects

  2. Associates the headers and footer objects with the DOCX or PDF PageLayout object that defines the properties of the section that contains the headers and footers

  3. Adds the headers and footers to your report as your code navigates the sections defined by the template

As your report program navigates the sections, it can append content to the template-defined headers and footers.

Use Page Headers and Footers in a Template

You can insert page headers and footers in the main template or in a document part template. The approach differs for Word and for PDF.

Page Headers and Footers in a Word Template

Every page in a Word document has a header and footer that you can edit. To enable editing mode, double-click the header or footer area. Alternatively, on the Word Insert tab, in the Header & Footer section, click the Header or Footer button arrow. From the menu, select the corresponding Edit command. When you have finished editing the header or footer, on the Header & Footer Tools Design tab, click Close Header and Footer.

In editing mode, you can modify the header or footer by:

  • Inserting text, holes, page numbers, and images

  • Formatting the items you add, for example, by specifying the page number type

  • Resizing the header or footer

  • Specifying a different header or footer for the first page, odd pages, and even pages

  • Inserting Word fields

    The fields mechanism helps you to generate header or footer content that varies from page to page. To see the fields you can insert, click the Explore Quick Parts button and select Field. The StyleRef field is useful for inserting chapter or section titles in the footer. See Create Running Page Headers and Footers.

For details about working with Word page headers and footers, see the Word documentation.

You can modify the page headers and footers directly in the main template. To add a page header or footer in a document part template, modify the page header and footer as you want. Select the entire page using CTRL+A before you save the part to the Quick Parts Gallery. For details on adding and modifying document part templates, see Create a Microsoft Word Document Part Template Library.

You can insert a page number in a header or footer. On the Header & Footer Design tab, use the Page Number menu to insert a page number. To access formatting options, in the header or footer, right-click the page number and select Format Page Numbers.

Page Headers and Footers in a PDF Template

Adding page headers and footers in a PDF template involves these steps:

  • Add <pheader> and <pfooter> elements to a page layout that you define using the <layout> element. You can add the header and footer elements to the layout in the main template (root.html) or in a document part template.

  • Define a document part template for each page header or footer style.

Note

If you insert the header or footer into a layout only programmatically, you do not need to add the <pfooter> or <pheader> element to a template <layout> element.

The table shows the attributes that you can use with <pheader> and <pfooter>. These elements correspond with the DOM classes mlreportgen.dom.PDFPageHeader and mlreportgen.dom.PDFPageFooter.

ElementAttributesValues
pheadertypedefault, first, even
template-nameDocument part template that defines the header
pfootertypedefault, first, even
template-nameDocument part template that defines the footer

For example, this code defines a document part template Chapter that uses two page footers: one for odd pages and one for even pages. The page number format is Arabic numerals.

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

Define the document part templates MyPageFooter and MyEvenFooter in the docpart_templates.html file. For example, define the page footers so that:

  • All footers insert a page number. To insert a page number, use the <page> element.

  • The odd page numbers align right. The default value for type on the pfooter element specifies first and odd pages.

  • The even page numbers align left.

These document part templates define the page footers.

<dptemplate name="MyPageFooter">
    <p style="text-align:right;font-family:Arial,Helvetica,sans-serif;font-size:10pt">
    <page/></p>
</dptemplate>
<dptemplate name="MyEvenFooter">
    <p style="text-align:left;font-family:Arial,Helvetica,sans-serif;font-size:10pt">
    <page/></p>
</dptemplate>

These DOM API HTML elements are useful in headers and footers. For example, you can add page numbers to headers and footers in the form Page 1 of 3 using <page> and <numpages>. See mlreportgen.dom.NumPages for the equivalent programmatic approach. You can also generate content in the header or footer that changes based on the content of a specified element (style) on the page. See Create Running Page Headers and Footers.

PurposeElementAttributesValues
Page number format (same as first-page-number and page-number-format on layout)pnumberformatn or N for numeric, a, A, i, I
initial-valueThe number for the first page in the layout that uses this element
Current page number pageNo attributesn/a
Total number of pages in documentnumpagesNo attributesn/a
Insert content of a heading or other style into a page header or footer (for running headers and footers)stylerefNo attributesInserts content of nearest h1 element.
style-name orName of the style with content to insert in the header or footer, or
outline-levelOutline level of style with content to insert in the header or footer

Access Template-Defined Headers and Footers

Use the CurrentPageLayout property of a Document or DocumentPart object to access the template-defined headers and footers for the current section of a document or document part.

The value of the CurrentPageLayout property is a DOCXPageLayout or PDFPageLayout object whose PageHeaders and PageFooters properties contain a cell array of objects corresponding to the template-defined headers and footers of the current section. Each cell array can contain up to three objects, depending on how many of the three types of headers and footers (first page, even page, odd page) you define for the section. The objects can appear in any order in the cell array. Thus, to access a header or footer of a particular type, search the cell array to find the one you want to access.

Append Content to a Template-Defined Header or Footer

You can use the DOM API to append content to a template-defined header or footer that appears on every page in a section. To append content to a header or footer in the current section of a document or document part, first use the document or document part CurrentPageLayout property to access the DOCX or PDF PagerHeader or PageFooter object. Then use the append method of a PageHeader or PageFooter object to append content.

Header and footer objects are a type of document part object. You can append any kind of content to a page header or footer that you can append to a document part, for example, paragraphs, images, and tables.

You can use holes in the header and footers of your main template to control the positioning of content that you append to the headers and footers. For example, this program appends today’s date to a hole named Date on the first template-defined page header of the first section of a report. This example assumes that the Word template MyReportTemplate has one layout that defines a first page, odd page, and even page header and footer.

import mlreportgen.dom.*;
d = Document('MyReport','docx','MyReportTemplate');
open(d);

sect = d.CurrentPageLayout;

for i = 1:numel(sect.PageHeaders)
    if strcmpi(sect.PageHeaders(i).PageType,'first')
        firstPageHeader = sect.PageHeaders(i); 
        while ~strcmp(firstPageHeader.CurrentHoleId,'#end#')
            switch firstPageHeader.CurrentHoleId
                case 'Date'
                    append(firstPageHeader,date);                       
            end
            moveToNextHole(firstPageHeader);
        end
        break;
    end
end

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

Create Running Page Headers and Footers

A running page header or footer contains content that varies from page to page based on context. For example, the name of the current chapter or section changes from page to page. You can insert the current content in a page header or footer.

You can create running page headers and footers programmatically or in a template.

Create Running Page Headers and Footers in a Template

Page Headers and Footers in a Word Template describes the general approach to editing page headers and footers in Word. To add running text, insert a StyleRef field. This field is equivalent to the DOM API mlreportgen.dom.StyleRef class. To insert this field in a Word template or document part template:

  1. Open the header or footer for editing.

  2. On the Insert tab, from the Quick Parts button menu, select Field.

  3. In the Field dialog box, from the Field names list, select StyleRef. From the Style name list, select the name of the style that contains the text that you want to include in the running header or footer.

    For example, select Heading 1 to use the content of paragraphs formatted with the Heading 1 style. Your report must create content that uses that style for the content to appear in the header or footer.

  4. Click OK.

For PDF documents, to include running text, use a <styleref> element. Add code like this to your template’s docpart_templates.html library file. The <styleref> element uses the Heading1 object for the content by default.

<dptemplate name="RunningFooter">
    <p style="text-align:center;font-family:sans-serif;font-size:10pt">
         <styleref/>
    </p>
 </dptemplate>

To see the effect, add the page footer in the <layout> element of your template’s root.html file. You can insert it in any <layout> element your template defines.

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

Use code that creates Heading1 objects and calls your template to see the result. This code assumes that you defined the footer document part template in the template RunFooters.

import mlreportgen.dom.*;
d = Document('mydoc','pdf','RunFooters');
open(d);

title = append(d, Paragraph('Document Title'));
title.Bold = true;
title.FontSize = '28pt';

h1 = append(d,Heading1('My First Chapter'));
p1 = append(d,Paragraph('Hello World'));

h2 = append(d,Heading1('My Second Chapter'));
h2.Style = {PageBreakBefore(true)};
p2 = append(d,Paragraph('Text for this chapter.'));

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

To refer to the page footer programmatically, use code in this form. The first argument is the type of footer, the second is the template package, and the third is the document part template.

PDFPageFooter('default','RunFooters','RunningFooter');

This code creates the footer in the current page layout without relying on the template to insert the footer. It uses the template only for the definition of the document part template.

import mlreportgen.dom.*;
d = Document('mydoc','pdf','RunFooters');
open(d);

myfooter = PDFPageFooter('default','RunFooters','RunningFooter');
d.CurrentPageLayout.PageFooters = myfooter;

title = append(d,Paragraph('Document Title'));
title.Bold = true;
title.FontSize = '28pt';

h1 = append(d,Heading1('My First Chapter'));
p1 = append(d,Paragraph('Hello World'));

h2 = append(d,Heading1('My Second Chapter'));
h2.Style = {PageBreakBefore(true)};
p2 = append(d,Paragraph('Text for this chapter.'));

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

Create Running Page Headers and Footers Programmatically

The DOM API provides classes that help you to create running headers and footers programmatically in Word and PDF documents.

Create Page Headers and Footers Programmatically

Programmatically create a page header or footer in the current section of a report. You can use the same technique for PDF, using PDFPageHeader and PDFPageFooter in place of the corresponding DOCX parts.

  1. Use the DOCXPageHeader or DOCXPageFooter constructor to create the desired type of page header or footer (first page, odd page, even page, or odd and even page) based on a template that defines template form (the fixed content and holes for variable content).

  2. Fill the holes in the header or footer with content.

  3. Insert the header or footer in the array of page headers or footers of the current PageLayout object.

This code creates a first page header from a template stored in the document part template library of a report.

import mlreportgen.dom.*;
d = Document('MyReport','docx','MyReportTemplate');
open(d);
 
pageHeaders(1) = DOCXPageHeader('first',d,'FirstPageHeader');

while ~strcmp(pageHeaders(1).CurrentHoleId,'#end#')
    switch pageHeaders(1).CurrentHoleId
        case 'Date'
            append(pageHeaders(1),date);
    end
    moveToNextHole(pageHeaders(1));
end
 
d.CurrentPageLayout.PageHeaders = pageHeaders;

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

See Also

Functions

Classes

Related Topics