Skip to content

Commit 3f3791f

Browse files
euphariseupharis
committed
define header structure
1 parent bab2801 commit 3f3791f

File tree

3 files changed

+215
-67
lines changed

3 files changed

+215
-67
lines changed

‎docs/dev/analysis/features/header-footer.rst

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
=================
2+
Header and Footer
3+
=================
4+
5+
Word supports headers and footers on documents. Headers and footers can include paragraphs with styles, text, and images.
6+
7+
Many documents use headers in order to have a logo at the top of every page.
8+
9+
Or use a footer to have company contact information at the bottom of every page.
10+
11+
Structure
12+
=========
13+
14+
A header consists of five parts:
15+
16+
1. /word/header1.xml
17+
--------------------
18+
19+
This file contains the header contents. It could be named anything but it is often named header1.
20+
21+
A file can contain multiple headers and/or multiple footers. Each one should be stored in a different file:
22+
``/word/header1.xml``, ``/word/header2.xml``, etc.
23+
24+
Here's a simple example:
25+
26+
.. code-block:: xml
27+
28+
<w:hdr xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
29+
<w:p>
30+
<w:pPr>
31+
<w:pStyle w:val="Header" />
32+
<w:rPr />
33+
</w:pPr>
34+
<w:r>
35+
<w:rPr />
36+
<w:t>This is a header.</w:t>
37+
</w:r>
38+
</w:p>
39+
</w:hdr>
40+
41+
Footers are identical to headers except they use the ``<w:ftr>`` tag instead of ``<w:hdr>``.
42+
43+
2. /word/_rels/document.xmls.rels
44+
---------------------------------
45+
46+
This file contains unique relationship ids between all the different parts of a document: settings, styles, numbering, images, themes, fonts, etc.
47+
48+
When a header or footer is present, it too will have a unique relationship id.
49+
50+
Here's an example, with the header as defined above having ``rId3``:
51+
52+
.. code-block:: xml
53+
54+
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
55+
<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings" Target="settings.xml"/>
56+
<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>
57+
<Relationship Id="rId3" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/header" Target="header1.xml"/>
58+
</Relationships>
59+
60+
3. /word/document.xml
61+
---------------------
62+
63+
This file is the motherload: it contains the bulk of the document contents.
64+
65+
With respect to the headers or footers though, this file contains very little:
66+
all it contains is a reference to the header or footer in the sentinel sectPr
67+
(the final and often only sectPr in a document just before the closing body tag)
68+
via the relationship id defined in ``/word/_rels/document.xml.rels``
69+
70+
Here's an example, again with the ``header1.xml`` as ``rId3``:
71+
72+
.. code-block:: xml
73+
74+
<w:body>
75+
...
76+
<w:sectPr>
77+
<w:headerReference w:type="default" r:id="rId3"/>
78+
<w:pgSz w:w="12240" w:h="15840"/>
79+
<w:pgMar w:top="1440" w:right="1800" w:bottom="1440" w:left="1800" w:header="720" w:footer="720" w:gutter="0"/>
80+
<w:cols w:space="720"/>
81+
<w:docGrid w:linePitch="360"/>
82+
</w:sectPr>
83+
</w:body>
84+
85+
Footers are identical to headers except they use the ``<w:footerReference>``
86+
instead of the ``<w:headerReference>`` tag.
87+
88+
The ``<w:headerReference>`` (if present) should be the first element of the sentinel sectPr,
89+
and the ``<w:footerReference>`` should be the next element.
90+
(The OpenXML SDK 2.5 docx validator gives a warning if the ``<w:headerReference>``
91+
is not the first element.)
92+
93+
4. /[Content Types].xml
94+
-----------------------
95+
96+
If the header is present, it needs to be added to the ``[Content Types].xml`` file. Like so:
97+
98+
.. code-block:: xml
99+
100+
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
101+
<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
102+
<Default Extension="xml" ContentType="application/xml"/>
103+
<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
104+
<Default Extension="jpeg" ContentType="image/jpeg"/>
105+
<Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
106+
<Override PartName="/word/settings.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml"/>
107+
<Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>
108+
<Override PartName="/word/header1.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml"/>
109+
</Types>
110+
111+
The footer if present also needs to be added. Its ``ContentType`` should be ``application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml``.
112+
113+
5. /word/_rels/header1.xml.rels (OPTIONAL)
114+
------------------------------------------
115+
116+
If the header has an image, it will also need to have its relationships file.
117+
118+
Suppose the header above had an image stored at ``/word//media/image1.png``:
119+
120+
.. code-block:: xml
121+
122+
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
123+
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
124+
<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="media/image1.png"/>
125+
</Relationships>
126+
127+
Note on Styles:
128+
---------------
129+
130+
The header and footer has access to all the normal styles defined in ``/word/styles.xml``.
131+
132+
133+
Candidate Protocol
134+
==================
135+
136+
The following methods are added to the main_document_part (aka docx.document.Document)
137+
138+
.. code-block:: python
139+
140+
class Document(ElementProxy):
141+
def clear_headers(self):
142+
""" clears all headers from a docx
143+
"""
144+
145+
def add_header(self):
146+
""" removes all existing headers from a docx then adds a new footer
147+
:returns: a new Header instance
148+
"""
149+
150+
def clear_footers(self):
151+
""" clears all footers from a docx
152+
"""
153+
154+
def add_footer(self):
155+
""" removes all existing footers from a docx then adds a new footer
156+
:returns: a new Footer instance
157+
"""
158+
159+
160+
(Note: a file could contain multiple headers or footers but the proposed protocol below only allows
161+
adding a single header / footer for now, for simplicities sake.
162+
163+
Documents with multiple heaeders will reuetrn )
164+
165+
Header
166+
------
167+
168+
.. code-block:: python
169+
170+
class Header(BlockItemContainer):
171+
""" Proxy object wrapping around a CT_Hdr <w:hdr> element
172+
173+
paragraph = header.add_paragraph()
174+
run_text = paragraph.add_run('foobar', style='FOO')
175+
run_img = paragraph.add_run()
176+
run_img.add_picture(logo, width, height)
177+
"""
178+
pass
179+
180+
Footer
181+
------
182+
183+
.. code-block:: python
184+
185+
class Footer(BlockItemContainer):
186+
""" Proxy object wrapping around a CT_Ftr <w:ftr> element
187+
188+
paragraph = footer.add_paragraph()
189+
run_text = paragraph.add_run('foobar', style='FOO')
190+
run_img = paragraph.add_run()
191+
run_img.add_picture(logo, width, height)
192+
"""
193+
pass
194+
195+
196+
197+
What currently works:
198+
199+
Clear Headers / Footers.
200+
Add Header / Footer.
201+
Add Header / Footer paragraph with style.
202+
Add Header / Footer paragraph run with style.
203+
Add Header / Footer paragraph run with image.
204+
Add Header / Footer paragraph run with other inline shapes (probably).
205+
206+
What might not work so hot:
207+
208+
Editing existing headers easily.
209+
210+
What does not work:
211+
212+
Adding a second header to a document that already has a header.
213+
(The `document.add_header` method clears all headers first.)
214+
But this sounds like an edge case. Maybe it's not needed.

‎docs/dev/analysis/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Feature Analysis
2323
features/shapes-inline
2424
features/shapes-inline-size
2525
features/picture
26+
features/header-footer
2627

2728

2829
Schema Analysis

‎docs/header_footer.rst

Lines changed: 0 additions & 67 deletions
This file was deleted.

0 commit comments

Comments
 (0)