Header and Footer¶
In a WordprocessingML document, a page header is text that is separated from the main body of text and appears at the top of a printed page. The page headers in a document are often the same from page to page, with only small differences in content, such as a section title or page number. Such a header is also known as a running head.
A page footer is analogous in every way to a page header except that it appears at the bottom of a page. It should not be confused with a footnote, which is not uniform between pages. For brevity’s sake, the term header is often used here to refer to what may be either a header or footer object, trusting the reader to understand its applicability to both object types.
In book-printed documents, where pages are printed on both sides, when opened, the front or recto side of each page appears to the right of the bound edge and the back or verso side of each page appears on the left. The first printed page receives the page-number “1”, and is always a recto page. Because pages are numbered consecutively, each recto page receives an odd page number and each verso page receives an even page number.
The header appearing on a recto page often differs from that on a verso page. Supporting this difference gives rise to the option to have an even-page header that differs from the default odd-page header in a document. This “both odd-and-even headers” option is applied at the document level and affects all sections of the document.
The header appearing on the first page of a section (e.g. a chapter) may differ from that appearing on subsequent pages. Supporting this difference gives rise to the option to set a distinct first-page header. This “different first-page-header” option is applied at the section level and may differ from section-to-section in the document.
In WordprocessingML, a header or footer appears within the margin area of a page. With
a few exceptions, a header or footer may contain all the types of content that can
appear in the main body, including text and images. Each header and footer has access to
the styles defined in /word/styles.xml
.
Each section has its own set of headers and footers, although a section can be configured to “inherit” headers and footers from the prior section. Each section can have three header definitions, the default header, even header, and first page header. When different even/odd headers are not enabled, the default header appears on both even and odd numbered pages. If even/odd headers are enabled, the default header is used for odd pages. A corresponding set of three footer definitions are also possible. All header/footer definitions are optional.
Open Questions¶
- What about a continuous section break? What is the header/footer behavior there?
Candidate Protocol¶
Every section has a header; it is never None:
>>> header = section.header
>>> header
<docx.hdrftr.Header object at 0x02468ACE>
There are three header properties on Section
: .header,
.even_page_header, and .first_page_header. All header objects share the
same properties and methods. There are three corresponding properties for the
footers.
Header is a subclass of BlockItemContainer
, from which it inherits the same
content editing capabilities as Document
, such as .add_paragraph().
If the w:headerReference element for a header is not present, the definition for that header is “inherited” from the prior section. This action is recursive, such that, for example, the header definition from the first section could be applied to the third section. A header that inherits its definition is said to be “linked to previous”. Perhaps counterintuitively, a header for the first section can be “linked to previous”, even though no previous section exists. The .is_linked_to_previous property is simply a test for the existence of a header definition in the current section:
>>> header.is_linked_to_previous
True
Editing operations transparently operate on the source header, the one in the first prior section having a header of that type (when one is not present in the current section). If no prior sections have a header, one is created in the first section of the document on the first constructive edit call:
>>> header = document.sections[0].header
>>> header.is_linked_to_previous
True
>>> header.text = 'foobar'
>>> header.is_linked_to_previous
False
Assigning False to .is_linked_to_previous creates a blank header for that section when one does not already exist:
>>> header.is_linked_to_previous
True
>>> header.is_linked_to_previous = False
>>> header.is_linked_to_previous
False
Conversely, an existing header is deleted from a section by assigning True to .is_linked_to_previous:
>>> header.is_linked_to_previous
False
>>> header.is_linked_to_previous = True
>>> header.is_linked_to_previous
True
The document settings object has a read/write .odd_and_even_pages_header_footer property that indicates verso and recto pages will have a different header. Any existing even page header definitions are preserved when .odd_and_even_pages_header_footer is False; they are simply not rendered by Word. Assigning True to .odd_and_even_pages_header_footer does not automatically create new even header definitions:
>>> document.settings.odd_and_even_pages_header_footer
False
>>> document.settings.odd_and_even_pages_header_footer = True
>>> section.even_page_header.is_linked_to_previous
True
Section has a read/write .different_first_page_header_footer property that indicates whether the first page of the section should have a distinct header. Assigning True to .different_first_page_header_footer does not automatically create a new first page header definition:
>>> section.different_first_page_header_footer
False
>>> section.different_first_page_header_footer = True
>>> section.different_first_page_header_footer
True
>>> section.first_page_header.is_linked_to_previous
True
Specimen XML¶
There are seven different permutations of headers:
The same header on all pages of the document:
<w:sectPr>
<w:headerReference w:type="default" r:id="rId3"/>
...
</w:sectPr>
Only an odd header. The section is exactly the same as above but settings.xml has the the <w:evenAndOddHeaders> property:
<w:settings xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
...
<w:evenAndOddHeaders w:val="1"/>
...
</w:settings>
Different even and odd headers:
<w:sectPr>
<w:headerReference w:type="default" r:id="rId3"/>
<w:headerReference w:type="even" r:id="rId4"/>
...
</w:sectPr>
Distinct first page header, subsequent pages all have the same header:
<w:sectPr>
<w:headerReference w:type="default" r:id="rId3"/>
<w:headerReference w:type="first" r:id="rId4"/>
<w:titlePg/>
...
</w:sectPr>
Distinct first, even, and odd page headers:
<w:sectPr>
<w:headerReference w:type="default" r:id="rId3"/>
<w:headerReference w:type="first" r:id="rId4"/>
<w:headerReference w:type="even" r:id="rId5"/>
<w:titlePg/>
...
</w:sectPr>
A header part:
<w:hdr>
<w:p>
<w:pPr>
<w:pStyle w:val="Header"/>
</w:pPr>
<w:r>
<w:t>Header for section-1</w:t>
</w:r>
</w:p>
</w:hdr>
Word Behavior¶
- When you turn off even/odd headers, Word sets the value of w:evenAndOddHeaders to 0, but does not actually remove the even header.
- When you turn off first page header, Word sets the value of w:titlePg to 0, but does not actually remove the even header.
- Word will load a file with an even page header but no odd page header.
MS API¶
WdHeaderFooterIndex Enumeration:
EVEN_PAGES = 3
FIRST_PAGE = 2
PRIMARY = 1
Create footer in MS API:
section = Document.Sections(1)
footers = section.Footers # a HeadersFooters collection object
default_footer = footers(wdHeaderFooterPrimary)
default_footer.Range.Text = "Footer text"
PageSetup object:
DifferentFirstPageHeaderFooter: Read/write {True, False, WD_UNDEFINED}
OddAndEvenPagesHeaderFooter: Read/write {True, False, WD_UNDEFINED}
Schema Excerpt¶
<xsd:complexType name="CT_SectPr"> <!-- denormalized -->
<xsd:sequence>
<xsd:choice minOccurs="0" maxOccurs="6"/>
<xsd:element name="headerReference" type="CT_HdrFtrRef"/>
<xsd:element name="footerReference" type="CT_HdrFtrRef"/>
</xsd:choice>
<xsd:element name="footnotePr" type="CT_FtnProps" minOccurs="0"/>
<xsd:element name="endnotePr" type="CT_EdnProps" minOccurs="0"/>
<xsd:element name="type" type="CT_SectType" minOccurs="0"/>
<xsd:element name="pgSz" type="CT_PageSz" minOccurs="0"/>
<xsd:element name="pgMar" type="CT_PageMar" minOccurs="0"/>
<xsd:element name="paperSrc" type="CT_PaperSource" minOccurs="0"/>
<xsd:element name="pgBorders" type="CT_PageBorders" minOccurs="0"/>
<xsd:element name="lnNumType" type="CT_LineNumber" minOccurs="0"/>
<xsd:element name="pgNumType" type="CT_PageNumber" minOccurs="0"/>
<xsd:element name="cols" type="CT_Columns" minOccurs="0"/>
<xsd:element name="formProt" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="vAlign" type="CT_VerticalJc" minOccurs="0"/>
<xsd:element name="noEndnote" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="titlePg" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="textDirection" type="CT_TextDirection" minOccurs="0"/>
<xsd:element name="bidi" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="rtlGutter" type="CT_OnOff" minOccurs="0"/>
<xsd:element name="docGrid" type="CT_DocGrid" minOccurs="0"/>
<xsd:element name="printerSettings" type="CT_Rel" minOccurs="0"/>
<xsd:element name="sectPrChange" type="CT_SectPrChange" minOccurs="0"/>
</xsd:sequence>
<xsd:attribute name="rsidRPr" type="ST_LongHexNumber"/>
<xsd:attribute name="rsidDel" type="ST_LongHexNumber"/>
<xsd:attribute name="rsidR" type="ST_LongHexNumber"/>
<xsd:attribute name="rsidSect" type="ST_LongHexNumber"/>
</xsd:complexType>
<xsd:complexType name="CT_HdrFtrRef">
<xsd:attribute ref="r:id" use="required"/>
<xsd:attribute name="type" type="ST_HdrFtr" use="required"/>
</xsd:complexType>
<xsd:simpleType name="ST_HdrFtr">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="even"/>
<xsd:enumeration value="default"/>
<xsd:enumeration value="first"/>
</xsd:restriction>
</xsd:simpleType>