Fields

Version 6.1.0

In this article

This article describes how fields are added to a MigraDoc document to automatically insert page numbers, document information, or the current date.

InfoFields

Using InfoField you can insert some of the document information (see Document / Document settings for more information). The AddInfoField method provides the iType parameter to select the property of the document’s DocumentInfo instance to display:

paragraph.AddInfoField(InfoFieldType.Title);

See full Example in PDFsharp.Sample repository. Show resulting PDF

The InfoFieldType enum used for the parameter comes with the values Title, Subject, Author and Keywords.

DateFields

A DateField instance will insert the current date and / or time into your text. By default, both are added:

paragraph.AddDateField();

See full Example in PDFsharp.Sample repository. Show resulting PDF

You can also provide any desired .NET date and time format string to change the output of the field. This line for example will render the date only:

paragraph.AddDateField("D");

See full Example in PDFsharp.Sample repository. Show resulting PDF

Beware that the text output of the DateField varies between cultures. If the code creating your document may be executed on machines with different cultures, you should define a culture to be used for your document. To change the culture of your document, check Document / Document settings.

Page and section number fields

There is a set of fields to insert the number or the count of pages or sections. Those will always output the up-to-date value when rendering your document.

A PageField instance will insert the number of the current page:

paragraph.AddPageField();

See full Example in PDFsharp.Sample repository. Show resulting PDF

You are not bound to output the page number as a decimal number. The Format property of the field can handle the following values for other number representations:

"ROMAN" renders a roman number in uppercase.

"roman" renders a roman number in lowercase.

"ALPHABETIC" renders an alphabetic representation in uppercase.

"alphabetic" renders an alphabetic representation in lowercase.

Just set the Format property after adding the field.

var field = paragraph.AddPageField();
field.Format = "ROMAN";

See full Example in PDFsharp.Sample repository. Show resulting PDF

The Format property can be also set for all the following page and section number fields.

Using PageRefField you can insert a reference to another page. As this field refers to a bookmark, you have to create one (see BookmarkFields). You then specify the bookmark name when you create and add the PageRefField instance:

paragraph.AddPageRefField(bookmark1);

See full Example in PDFsharp.Sample repository. Show resulting PDF

A NumPagesField instance will insert the total page count:

paragraph.AddNumPagesField();

See full Example in PDFsharp.Sample repository. Show resulting PDF

A SectionField instance will insert the number of the current section:

paragraph.AddSectionField();

See full Example in PDFsharp.Sample repository. Show resulting PDF

A SectionPagesField instance will insert the section’s page count:

paragraph.AddSectionPagesField();

See full Example in PDFsharp.Sample repository. Show resulting PDF

Controlling the page number

The shown page number rendered from PageField and PageRefField instances (see Page and section number fields) usually corresponds to the respective page number of the document. For PDF documents, you can influence these numbers by setting the StartingNumber property of the PageSetup instance of the section:

// Set the StartingNumber of the section,
// which will be considered for PageFields and PageRefFields.
section.PageSetup.StartingNumber = 9;

See full Example in PDFsharp.Sample repository. Show resulting PDF

Note that StartingNumber is inherited to the next section’s PageSetup instance like all of its properties (see Formats / Page setup for more information). If you don’t want the next section to start with the same page number, you have to set its StartingNumber to another value or reset it to null. If you reset it to null, it will be resumed with the last page number. You can reset the value to null by assigning a whole clone of another PageSetup instance with StartingNumber unset (see Formats / Page setup) or by setting its internal nullable value to null:

// Set the underlying nullable StartingNumber to null to resume with the last page number.
section.PageSetup.Values.StartingNumber = null;

See full Example in PDFsharp.Sample repository. Show resulting PDF

BookmarkFields

A bookmark is a special field, as it has no text output. According to its name, it marks a position in the document. Each bookmark shall have a unique name for identification. You can pass this name to hyperlinks (see Hyperlinks for more information) or PageRefFields (see Page and section number fields) to refer to the bookmark.

You can create and add a BookmarkField instance like this:

// Create a variable with the name of the bookmark.
var bookmark1 = "bookmark1";

// Prepend a bookmark to the paragraph for referring.
paragraph.AddBookmark(bookmark1);

See full Example in PDFsharp.Sample repository. Show resulting PDF

AddBookmark has an optional boolean parameter prepend. As a bookmark is usually positioned at the beginning of a paragraph, this parameter is true by default.

Of course, a bookmark can be created and added later to the document than its referring hyperlinks or PageRefFields. The bookmark names will be resolved on rendering.