Working with Sections

Sometimes you want a document that does not have the same formatting across all pages. For example, you may need to modify page number formats, have different page size and orientation, or have the first document page as a cover page without any numbering. You can achieve that with sections.

Sections are level nodes that control headers and footers, orientation, columns, margins, page number formatting, and others.

Aspose.Words allows you to manage sections, divide a document into sections, and make formatting changes that apply only to a specific section. Aspose.Words stores information about section formatting such as headers and footers, page setup, and column settings in the section break.

This article explains how to work with sections and section breaks.

What Section and Section Break Is

Document sections are represented by the Section and SectionCollection classes. Section objects are immediate children of the Document node and can be accessed via the sections property. You can manage those nodes by using some methods such as remove, add, index_of, and others.

Section break is an option that divides document pages into sections with customizable layouts.

Types of a Section Break

Aspose.Words allows you to split and format documents using different section breaks of the BreakType enumeration:

  • SectionBreakContinuous
  • SectionBreakNewColumn
  • SectionBreakNewPage
  • SectionBreakEvenPage
  • SectionBreakOddPage

You can also use the SectionStart enumeration to choose a break type that applies only for the first section such as NewColumn, NewPage, EvenPage, and OddPage.

Manage a Section

Since a section is a normal composite node, the entire node manipulation API can be used to manipulate sections: to add, remove, and other operations on sections. You can read more about nodes in the article Aspose.Words Document Object Model (DOM).

On the other hand, you can also use the DocumentBuilder API to work with sections. In this article, we will focus on this particular way of working with sections.

Insert or Remove a Section Break

Aspose.Words allows you to insert a section break into text using the insert_break method.

The following code example shows how to insert a section break into a document:

Use the remove method to delete a section break. If you do not need to remove a specific section break and instead delete the content of that section, you can use the clear_content method.

The following code example shows how to remove sections breaks:

Move a Section

If you want to move a section from one position to another in your document, you need to get the index of that section. Aspose.Words allows you to get a section position from a SectionCollection by index, using the indexer. You can use the sections property to get all sections in your document. But if you want to get only the first section, you can use the first_section property.

The following code example shows how to access the first section and iterate through the children of a composite node:

Specify a Section Layout

Sometimes you want your document to look better by making creative layouts for different document sections. If you want to specify the type of the current section grid, you can choose a section layout mode using the SectionLayoutMode enumeration:

  • Default
  • Grid
  • LineGrid
  • SnapToChars

The following code example shows how to limit the number of lines that each page may have:

Edit a Section

When you add a new section to your document, there will be no body or paragraph that you can edit. Aspose.Words allows you to guarantee that a section contains a body with at least one paragraph using the ensure_minimum method – it will automatically add a Body (or HeaderFooter) node to the document and then add a Paragraph to it.

The following code example shows how to prepare a new section node using ensure_minimum:

Append or Prepend Content

If you want to draw some shape or add text or image at the beginning/end of a section, you can use the append_content and prepend_content methods of the Section class.

The following code example shows how to append content of an existing section:

Clone a Section

Aspose.Words allows you to duplicate a section by creating a full copy of it using the clone method.

The following code example shows how to clone the first section in your document:

Copy Sections between Documents

In some cases, you may have large documents with many sections and you want to copy the content of a section from one document to another.

Aspose.Words allows you to copy sections between documents using the import_node method.

The following code example shows how to copy sections between documents:

The basic rules for displaying a header or footer for each section are quite simple:

  1. If the section does not have its own headers/footers of a certain type, then it is taken from the previous section.
  2. The type of header/footer displayed on the page is controlled by the “Different First Page” and “Different Odd & Even pages” section settings – if they are disabled, then the section’s own titles are ignored.

The following code example shows how to create 2 sections with different headers:

If you want to remove the text of headers and footers without removing HeaderFooter objects in your document, you can use the clear_headers_footers method. In addition, you can use the delete_header_footer_shapes method to remove all shapes from headers and footers in your document.

The following code example shows how to clear content of all headers and footers in a section:

The following code example how to remove all shapes from all headers footers in a section:

Customize Page Properties in a Section

Before printing a page or a document you may want to customize and modify the size and layout of a single page or the whole document. With page setup, you can change the settings of document pages such as margins, orientation, and size for printing different first pages or odd pages.

Aspose.Words allows you to customize page and section properties using the PageSetup class.

The following code example shows how to set such properties as page size and orientation for the current section:

The following code example shows how to modify the page properties in all sections:

See Also

Limitations and Considerations

  • When removing a section break, the section before the break adopts the formatting (including page setup, headers, and footers) of the section after the break. This is the opposite of what many developers expect. To avoid unintended layout changes, ensure you understand the section order before removal.

  • The ensure_minimum() method only ensures the presence of a Body and at least one Paragraph. It does not create HeaderFooter nodes. To add a header or footer, create it and add it to the section, e.g., section.headers_footers.add(aw.HeaderFooter(doc, aw.HeaderFooterType.HEADER_PRIMARY)).

  • section.clone() copies the section together with its HeaderFooter nodes. To insert the copy into another document, import it with import_node or NodeImporter. To stop a section from using the headers and footers of the previous section, call section.headers_footers.link_to_previous(False).

  • When copying sections between documents using node_importer.import_node(), specify aw.ImportFormatMode.KEEP_SOURCE_FORMATTING to preserve source formatting. Without it, the section may adopt formatting from the target document, potentially causing layout shifts.

  • Headers and footers are inherited from the previous section unless the current section has its own HeaderFooter nodes. To break the inheritance and enable independent editing, create or import a HeaderFooter for the desired type (e.g., HeaderFooterType.HEADER_PRIMARY) and ensure the section’s page_setup.different_first_page_header_footer and page_setup.odd_and_even_pages_header_footer settings match your intent.

  • page_setup.layout_mode (see SectionLayoutMode) defines the document grid behavior of a section.

FAQ

  1. Q: How can I insert a specific type of section break (e.g., new page or continuous) using Python?
    A: Use the DocumentBuilder.insert_break method and pass the desired BreakType enumeration value, such as BreakType.SECTION_BREAK_NEW_PAGE or BreakType.SECTION_BREAK_CONTINUOUS. The builder inserts the break at the current cursor position.

  2. Q: What is the recommended way to move a section to a different position in the document?
    A: Retrieve the section from the Document.sections collection, remove it with sections.remove(section), and then insert it at the new index using sections.insert(index, section). This preserves the section’s formatting and content.

  3. Q: How do I copy a section from one document into another without losing its formatting?
    A: Load both documents, obtain the source Section, and import it into the target document with a NodeImporter: importer = aw.NodeImporter(src_doc, dst_doc, aw.ImportFormatMode.KEEP_SOURCE_FORMATTING), then importer.import_node(source_section, True). Then add the imported node to the target document’s sections collection.

  4. Q: Can I clear the text of headers and footers without deleting the header/footer objects themselves?
    A: Yes. Call Section.clear_headers_footers() to remove all header/footer text while keeping the objects intact. If you also need to remove shapes, use Section.delete_header_footer_shapes() afterwards.

  5. Q: When I create a new section, why does it sometimes lack a body or paragraph, and how can I ensure it has one?
    A: A newly created Section may be empty. Invoke Section.ensure_minimum() which automatically adds a Body node and at least one empty Paragraph, allowing you to start inserting content immediately.

Working with Styles and Themes Working with Ranges in Python