Understanding Sections and how to use them

Learn more about Xceed Words for .NET

 

In the previous article, we saw the basics of creating a docx document using the Create, Load, Save and SaveAs methods, as well as how to add Paragraphs and append a little text to them.

Before going into what other elements can be added to a document, we will first learn about Sections.

 

Introduction

When a Document is first created, by default it only includes 1 Section. This default Section includes the 3 header/footer types (First, Even and Odd), as well as the default formatting parameters.

When a new Section is added to a Document, it is appended at the end of the Document, and starts on a new page (a given page will never have 2 Sections overlapping on it).

 

Why use different Sections

To understand why you might want to have more than one Section in your Document, let’s look at a list of some of the useful properties you can customize on each Section:

• Headers / Footers

• Margins (top, bottom, left, right, header, footer, mirror margins)

• Page settings (height, width, borders, layout, number start)

• and more (hyperlinks, lists, pictures, shapes, tables, etc.)

If you have a document in which you have groups of pages for which you would want different sets of values for these properties, you would put each group of pages in its own Section.

For example: a user’s manual with Sections for the cover page, the Table of Content, the chapters that make the main body, and finally for the conclusion and/or annex pages at the end:

1. Cover page: only a main title centered on the screen, no headers/footers displayed.

2. Table of content: custom headers/footers #1, pages do count but numbers are not displayed.

3. Main content: custom headers/footers #2, pages do count, and numbers are now displayed.

4. Conclusion/Annex pages: custom headers/footers #3

 

Retrieving the existing Sections

 To retrieve the list of existing Sections of a Document, we call its GetSections method:

// Open an existing document
using( var document = DocX.Load( "ExistingDocument.docx" ) )
{
	var sections = document.GetSections();
	// ...
}

 

Adding new Sections

To add a new Section to a Document, we call the Document's InsertSectionPageBreak method.

Below is a more complete example that also demonstrates how Sections can be customized through some of their properties.

First, let’s create a new document, and make changes to the default Section: 

using( var document = DocX.Create( "InsertSections.docx" ) )
{
	// Different odd and even pages headers/footers
	document.DifferentOddAndEvenPages = true;

	// Section 1 – Set footers
	document.Sections[0].AddFooters();
	document.Sections[0].DifferentFirstPage = true;
	var footers = document.Sections[ 0 ].Footers;
	footers.First.InsertParagraph( "This is the First page footer." );
	footers.Even.InsertParagraph( "This is the Even page footer." );
	footers.Odd.InsertParagraph( "This is the Odd page footer." );

	// Section 1 - Add paragraphs and page breaks
	document.InsertParagraph( "FIRST" ).InsertPageBreakAfterSelf();
	document.InsertParagraph( "SECOND" ).InsertPageBreakAfterSelf();
	document.InsertParagraph( "THIRD" );

 

Next, let’s add another Section and give it a different page size:

	// Add a Section Break to end the previous section and add a new one
	// The new section’s properties will be based on the last section’s properties
	document.InsertSectionPageBreak();

	// Section 2 - Set page parameters
	document.Sections[ 1 ].PageWidth = 200f;
	document.Sections[ 1 ].PageHeight = 300f;

	// Section 2 - Set footers
	document.Sections[ 1 ].AddFooters();
	document.Sections[ 1 ].DifferentFirstPage = true;
	var footers2 = document.Sections[ 1 ].Footers;
	footers2.First.InsertParagraph( "This is the First page footer of Section 2." );
	footers2.Odd.InsertParagraph( "This is the Odd page footer of Section 2." );
	footers2.Even.InsertParagraph( "This is the Even page footer of Section 2." );

	// Section 2 - Add paragraphs and page breaks
	document.InsertParagraph( "FOURTH" ).InsertPageBreakAfterSelf();
	document.InsertParagraph( "FIFTH" ).InsertPageBreakAfterSelf();
	document.InsertParagraph( "SIXTH" );

 

Finally, let’s add one final Section, give it a new page size and custom margins:

	// Add a Section Break to end the previous section and add a new one
	// The new section’s properties will be based on the last section’s properties
	document.InsertSectionPageBreak();

	// Section 3 - Set page and margin parameters
	document.Sections[ 2 ].PageWidth = 595f;
	document.Sections[ 2 ].PageHeight = 841f;
	document.Sections[ 2 ].MarginTop = 300f;
	document.Sections[ 2 ].MarginFooter = 120f;

	// Section 3 - Set footers
	document.Sections[ 2 ].AddFooters();
	document.Sections[ 2 ].DifferentFirstPage = true;
	var footers3 = document.Sections[ 2 ].Footers;
	footers3.First.InsertParagraph( "This is the First page footer of Section 3." );
	footers3.Odd.InsertParagraph( "This is the Odd page footer of Section 3." );
	footers3.Even.InsertParagraph( "This is the Even page footer of Section 3." );

	// Section 3 - Add paragraphs and page breaks
	document.InsertParagraph( "SEVENTH" ).InsertPageBreakAfterSelf();
	document.InsertParagraph( "EIGHTH" ).InsertPageBreakAfterSelf();
	document.InsertParagraph( "NINTH" );

	// Save this document to disk.
	document.Save();
}

 

For more information, please refer to the documentation.