6. Customization of the document

Docxbuilder provides two ways to customize generated documents. The one is style file, and another is class based customization.

6.1. Style file

The generated document inherits some properties from the style file, which may be referenced by docx_style configuration. The inherited properties are

• styles of the document contents,
• cover page, and,
• section settings (size, margins, borders, header, footer, etc.).

The contents in the style file are ignored.

If you want to change these properties, you must create a new style file. The lists of styles used by Docxbuilder, see Section 6.1.1. About cover page, see Section 6.1.3. About section settings, see Section 6.1.4.

6.1.1. Document style

In OpenXML, there are multiple style types. Docxbuilder uses character, paragraph, and table styles. The character styles are described in character_style_table, the paragraph styles are described in paragraph_style_table, and the table styles are described in table_style_table.

Style automatic generation

If some styles are not defined in the style file, Docxbuilder automatically generate the styles from other defined styles. Fig. 6.1.1 and Fig. 6.1.2 represents which style is generated from which style.

Fig. 6.1.1 Generation relationship for paragraph styles

Fig. 6.1.2 Generation relationship for table styles

Footnotes

[1]	The Problematic style is used only when some errors exists in documents (e.g. using non-exsistence cross reference, unknown rorles). Then it is almost unnecessary to define this style.

[2]	This is Footnote Text.

6.1.2. User defined styles

In addition to above styles, you can define your original styles. These styles are applied to elements with the corresponding class name The mapping from class name to original style are defined by docx_style_names configuration.

docx_style = 'path/to/custom-style.docx'
docx_style_names = {
   'strike': 'Strike',
   'custom-table': 'Custom Table',
}
# And define Strike and Custom Table styles in the style file specified docx_style

The following reStructuredText show how to use the custom styles.

.. Use role to specify character class name.
.. role:: strike

This :strike:`text` is striked.

.. list-table:: Custom style table
   :class: custom-table

   * - Row1: Col1
     - Row1: Col2
   * - Row2: Col1
     - Row2: Col2

Warning

Currently, only table elements and character elements are enable to be applied user defined styles.

6.1.3. Cover page

If docx_coverpage is true, the cover page of the style file is inserted into the generated document. Docxbuilder treat the first structured document tag with “Cover Pages” docPartGallery as the cover page. If no tag is found, the contents far to the first section break are used as the cover page. If no section break is found, the contents far to the first page break are used as the cover page.

How to create structured document tag with “Cover Pages” docPartGallery

It seems that Office Word can not create only structured document tag. Therefore, if you want to create your original cover page, you must insert a pre designed cover page and then modify the cover page.

6.1.4. Section settings

The generated document inherits the section settings from the style file. The settings includes header, footer, page size, page margins, page borders, and so on.

If the style file includes multiple sections, Docxbuilder apply the first section. If you want to apply other section from the middle of the document, use Docxbuilder custom class. In the bellow example, section A and C use the first section settings, and section B uses the second section settings.

Listing 6.1.1 Example to specify section settings

Section A
=========

contents

.. Use 2nd section from the next section
.. rst-class:: docx-section-portrait-1

Section B
=========

contents

.. Use 1st section from the next section
.. rst-class:: docx-section-portrait-0

Section C
=========

contents

6.2. Class based customization

Docxbuilder provides class based customization. Elements with special classes which has “docx-” prefix, are arranged based on the specified class by Docxbuilder.

In the bellow example, the table is arranged in landscape page. This is useful for tables with many columns, or horizontally long figures.

.. csv-table::
   :class: docx-landscape

   A,B,C,D,E,F,G,H,I,J,K,L,M,N,O,P,Q,R,S,T,U,V,W,X,Y,Z
   1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26

Table 6.2.1 shows the list of custom classes. For each class, kinds of elements enable to be applied the class are defined.

Table 6.2.1 Speciall custom class list

Class	Target	Description
docx-section-portrait-N docx-section-landscape-N	section	Use Nth portrait or landscape section in style file from the section. N of the first section is 0.
docx-rotation-header-N	table	Rotate the table header and the height is N% of the width.
docx-landscape docx-no-landscape	figure, table	Arrange the figure or table in landscape page, or not.
docx-in-single-page docx-no-in-single-page	table	Arrange the table in single page as much as possible, or not.
docx-row-splittable docx-no-row-splittable	table	Allow to split the table row into multiple pages, or not.
docx-header-in-all-page docx-no-header-in-all-page	table	Always show the table header when the table is arranged in multiple pages, or not.