Document Solutions for Word
Features / Fields / Update Fields
In This Topic
    Update Fields
    In This Topic

    DsWord allows you to update the results of supported fields in the document using UpdateFields and Update methods. UpdateFields method of GcWordDocument and RangeBase classes enables you to update all supported fields in the document or all fields that support updating in the range. Meanwhile, Update method of ComplexField and SimpleField classes allows you to update the supported field results. See Field Type Options for more information.

    Refer to the following example code to add TOC fields and hide the page number for the 'Heading 1' TOC entry:

    C#
    Copy Code 
    // Initialize GcWordDocument.
GcWordDocument doc = new GcWordDocument();
            
// Create TOC field options.
TocFieldOptions options = new TocFieldOptions(doc);

// Build TOC with paragraphs.
foreach (TocStyleLevel style in options.Styles)
{
    switch (style.Level)
    {
        case OutlineLevel.Level1:
        case OutlineLevel.Level2:
        case OutlineLevel.Level3:
            style.Collect = true;
            break;
        default:
            style.Collect = false;
            break;
    }
}
            
// Add TOC field.
ComplexField field = doc.Body.AddParagraph().AddComplexField(options);

// Add a paragraph with Heading 1 style.
doc.Body.AddParagraph("Heading 1", doc.Styles[BuiltInStyleId.Heading1]);

// Add normal text for the heading and create next section.
doc.Body.AddParagraph("Document Solutions").AddSectionBreak();

// Add a paragraph with Heading 2 style.
doc.Body.AddParagraph("Heading 2", doc.Styles[BuiltInStyleId.Heading2]);

// Add normal text for the heading and create next section.
doc.Body.AddParagraph("Document Solutions for Word").AddSectionBreak();

// Add a paragraph with Heading 3 style.
doc.Body.AddParagraph("Heading 3", doc.Styles[BuiltInStyleId.Heading3]);
            
// Add normal text for the heading.
doc.Body.AddParagraph("DsWord");

// Update the field.
field.Update();

            
// Get first TOC field.
field = doc.Body.ComplexFields.First;
            
// Parse field options.
options = new TocFieldOptions(field);
            
// Hide page numbers for the first level TOC entries.
options.PageNumbers.OmitLevels.Set(OutlineLevel.Level1, OutlineLevel.Level1);
            
// Change TOC field instructions.
options.Save(field);
            
// Update all document fields.
doc.UpdateFields();

// Save the document.
doc.Save("TOC.docx");

    Field Type Options

    DsWord supports strong-typed access to the options of specific field types to read and write arguments and switches using PageFieldOptions, PageRefFieldOptions, SectionFieldOptions, SectionPagesFieldOptions, SeqFieldOptions, TcFieldOptions, and TocFieldOptions classes.

    PageFieldOptions, PageRefFieldOptions, SectionFieldOptions, SectionPagesFieldOptions, and SeqFieldOptions classes inherit FieldFormatOptions class that provides options to format the field result. The following table lists the options available in FieldFormatOptions class:

    Options Description
    Load method Loads options from a simple field or a complex field.
    Save method Saves options to a simple field or a complex field.
    NumberFormat property This property gets or sets the number format.
    NumberStyle property This property gets or sets the number formatting style.
    StringStyle property This property gets or sets the string formatting style.
    ResultFormat property This property gets or sets the result formatting rule.

    Furthermore, DsWord also provides Add, AddComplexField, and Insert overload methods that accept IFieldOptions to add or insert specific types of fields. Refer to the following sections for more information and to add the supported fields:

    PAGE Field Options

    PAGE field inserts the page number on which it is present. Refer to the following example code to add PAGE field and specify its options:

    C#
    Copy Code 
    // Initialize GcWordDocument.
var doc = new GcWordDocument();

// Set PAGE field for the page header.
var pgOptHeader = new PageFieldOptions(doc);
pgOptHeader.NumberStyle = NumberStyle.Decimal;

// Set PAGE field for page numbers in the body.
var pgOptBody = new PageFieldOptions(doc);
pgOptBody.NumberStyle = NumberStyle.UpperRoman;

// Add page header that includes the page number.
doc.Body.Sections.First.Headers[HeaderFooterType.Primary].Body.AddParagraph("Page Header - Page ").AddComplexField(pgOptHeader);

// Set style for page numbers in the document body.
var pageStyle = doc.Styles[BuiltInStyleId.IndexHeading];

// Add pages with periodic inclusions of the PAGE field.
var rnd = Util.NewRandom();
for (int i = 0; i < rnd.Next(6, 12); i++)
{
    var p = doc.Body.AddParagraph("This text is on page ", pageStyle).AddComplexField(pgOptBody);
    p.GetRange().Runs.Add(".");
    var par = Util.LoremIpsumPar();
    doc.Body.AddParagraph(par);
}

// Update fields using specific culture.
doc.UpdateFields(new GrapeCity.Documents.Word.Layout.WordLayoutSettings() { FontCollection = Util.FontCollection, Culture = CultureInfo.GetCultureInfo("en-US") });
            
// Save the document.
doc.Save("PageFieldOptions.docx");

    PAGEREF Field Options

    PAGEREF field inserts the page number of a bookmark for a cross-reference. PageRefFieldOptions class provides the following options along with the options inherited from FieldFormatOptions class:

    Option Description
    Bookmark Sets the bookmark name for a cross-reference.
    Hyperlink Indicates whether to create a hyperlink to the bookmarked paragraph.
    DisplayRelative Indicates whether to display the position relative to the source bookmark.

    Refer to the following example code to add PAGEREF field and specify its options:

    C#
    Copy Code 
    // Initialize GcWordDocument.
var doc = new GcWordDocument();

// Set bookmark name.
const string bmkName = "bmk";

// Set PAGEREF field options.
var pgRefOpt = new PageRefFieldOptions(doc, bmkName);
pgRefOpt.NumberStyle = NumberStyle.UpperRoman;
pgRefOpt.Hyperlink = true;

// Add a page header that includes the page number.
var pgOptHeader = new PageFieldOptions(doc);
pgOptHeader.NumberStyle = NumberStyle.Decimal;
doc.Body.Sections.First.Headers[HeaderFooterType.Primary].Body.AddParagraph("Page Header - Page ").AddComplexField(pgOptHeader);

// Add a paragraph with the PAGEREF.
var p = doc.Body.AddParagraph("Go to page ", doc.Styles[BuiltInStyleId.IndexHeading]).AddComplexField(pgRefOpt);
p.GetRange().Runs.Add("...");

// Add content.
var rnd = Util.NewRandom();
for (int i = 0; i < rnd.Next(20, 25); i++)
{
    doc.Body.AddParagraph(Util.LoremIpsumPar());
}

// End with the bookmarked paragraph.
doc.Body.AddParagraph("The End.").GetRange().Bookmarks.Add(bmkName);

// Update fields using specific culture.
doc.UpdateFields(new GrapeCity.Documents.Word.Layout.WordLayoutSettings() { FontCollection = Util.FontCollection, Culture = CultureInfo.GetCultureInfo("en-US") });
            
// Save the document.
doc.Save("PageRefFieldOptions.docx");

    SECTION Field Options

    SECTION field inserts the number of the current section. Refer to the following example code to add SECTION field and specify its options:

    C#
    Copy Code 
    // Initialize GcWordDocument.
var doc = new GcWordDocument();

// Set PAGE field for the page header.
var pgOptHeader = new PageFieldOptions(doc);
pgOptHeader.NumberStyle = NumberStyle.Decimal;

// Set SECTION field for number of the section in the body.
var pgOptBody = new SectionFieldOptions(doc);
pgOptBody.NumberStyle = NumberStyle.UpperRoman;

// Add page header that includes the page number.
doc.Body.Sections.First.Headers[HeaderFooterType.Primary].Body.AddParagraph("Page Header - Page ").AddComplexField(pgOptHeader);

// Set style for page numbers in the document body.
var pageStyle = doc.Styles[BuiltInStyleId.IndexHeading];

// Add pages with periodic inclusions of the SECTION field.
var rnd = Util.NewRandom();
for (int i = 0; i < rnd.Next(6, 12); i++)
{
    var p = doc.Body.AddParagraph("Section ", pageStyle).AddComplexField(pgOptBody);
    var par = Util.LoremIpsumPar();
    doc.Body.AddParagraph(par);
    doc.Body.Paragraphs.Add().AddSectionBreak();
}

// Update fields using specific culture.
doc.UpdateFields(new GrapeCity.Documents.Word.Layout.WordLayoutSettings() { FontCollection = Util.FontCollection, Culture = CultureInfo.GetCultureInfo("en-US") });

// Save the document.
doc.Save("SectionFieldOptions.docx");

    SECTIONPAGES Field Options

    SECTIONPAGES field inserts the total number of pages in a section. Refer to the following example code to add SECTIONPAGES field and specify its options:

    C#
    Copy Code 
    // Initialize GcWordDocument.
var doc = new GcWordDocument();

// Set PAGE field for the page header.
var pgOptHeader = new PageFieldOptions(doc);
pgOptHeader.NumberStyle = NumberStyle.Decimal;

// Set SECTIONPAGES field for page number in the body.
var pgOptBody = new SectionPagesFieldOptions(doc);
pgOptBody.NumberStyle = NumberStyle.UpperRoman;

// Add page header that includes the page number.
doc.Body.Sections.First.Headers[HeaderFooterType.Primary].Body.AddParagraph("Page Header - Page ").AddComplexField(pgOptHeader);

// Set style for page numbers in the document body.
var pageStyle = doc.Styles[BuiltInStyleId.IndexHeading];

// Add SECTIONPAGES field.
var p = doc.Body.AddParagraph("This text of this section is present on ", pageStyle).AddComplexField(pgOptBody);
p.GetRange().Runs.Add(" pages.");

// Add pages with content.
var rnd = Util.NewRandom();
for (int i = 0; i < rnd.Next(6, 12); i++)
{
    var par = Util.LoremIpsumPar();
    doc.Body.AddParagraph(par);   
}

// Update fields using specific culture.
doc.UpdateFields(new GrapeCity.Documents.Word.Layout.WordLayoutSettings() { FontCollection = Util.FontCollection, Culture = CultureInfo.GetCultureInfo("en-US") });

// Save the document.
doc.Save("SectionPagesFieldOptions.docx");

    SEQ Field Options

    SEQ field numbers the chapters, tables, figures, and other items in a document sequentially. SeqFieldOptions class provides the following options along with the options inherited from FieldFormatOptions class:

    Option Description
    Id Sets the name assigned to the series of items that are to be numbered.
    Bookmark Sets the bookmark name that refers to an item elsewhere in the document rather than in the current location.
    Behavior Sets the field behavior.
    ResetTo Sets the value to reset the sequence if Behavior property is ResetTo.
    ResetAt Sets the built-in heading style OutlineLevel at which to reset the sequence if Behavior property is ResetAt.
    Hidden Indicates whether to hide the field result.

    Refer to the following example code to add SEQ field and specify its options:

    C#
    Copy Code 
    // Initialize GcWordDocument.
var doc = new GcWordDocument();

// Set SEQ field ID.
string id = "ID";

// Set SEQ field for sequence in the body.
var pgOptBody = new SeqFieldOptions(doc, id);

// Start sequence with 5.
pgOptBody.Behavior = SeqFieldBehavior.ResetTo;
pgOptBody.ResetTo = 5;

// Set number style to upper roman.
pgOptBody.NumberStyle = NumberStyle.UpperRoman;

// Set style for page numbers in the document body.
var pageStyle = doc.Styles[BuiltInStyleId.IndexHeading];

// Add pages with periodic inclusions of the SECTION field.
var rnd = Util.NewRandom();
for (int i = 0; i < rnd.Next(6, 12); i++)
{
    var p = doc.Body.AddParagraph("Section ", pageStyle).AddComplexField(pgOptBody);
    var par = Util.LoremIpsumPar();
    doc.Body.AddParagraph(par);
    doc.Body.Paragraphs.Add().AddSectionBreak();
}

// Set behavior for the second SEQ field.
pgOptBody.Behavior = SeqFieldBehavior.Next;

// Set number style to decimal.
pgOptBody.NumberStyle = NumberStyle.Decimal;

// Add content to the section.
var p1 = doc.Body.AddParagraph("Section ", pageStyle).AddComplexField(pgOptBody);
var par1 = Util.LoremIpsumPar();
doc.Body.AddParagraph(par1);
doc.Body.Paragraphs.Add().AddSectionBreak();

// Update fields using specific culture.
doc.UpdateFields(new GrapeCity.Documents.Word.Layout.WordLayoutSettings() { FontCollection = Util.FontCollection, Culture = CultureInfo.GetCultureInfo("en-US") });

// Save the document.
doc.Save("SEQFieldOptions.docx");

    TC Field Options

    TC field specifies the text and page numbers for entries in a table of contents and in lists of tables, figures, and similar contents. TcFieldOptions class provides the following options:

    Option Description
    Load Loads options from a simple field or complex field.
    Save Saves options to a simple field or complex field.
    Content Gets the TOC item content.
    Type Sets the type of entry collected in a particular contents list.
    DisplayLevel Sets the level to display entry in a TOC field result.
    OmitPageNumber Sets whether to omit the page number for the entry in a TOC field result.

    Refer to the following example code to add TC field and specify its options:

    C#
    Copy Code 
    // Initialize GcWordDocument.
var doc = new GcWordDocument();

// Add page header.
var pgOptHeader = new PageFieldOptions(doc);
pgOptHeader.NumberStyle = NumberStyle.Decimal;
var pgOptBody = new PageFieldOptions(doc);
doc.Body.Sections.First.Headers[HeaderFooterType.Primary].Body.AddParagraph("Page Header - Page ").AddComplexField(pgOptHeader);

// Set TOC field options.
var tocOpts = new TocFieldOptions(doc);
tocOpts.TcFields.Collect = true;

// Add TOC and a section break to the document.
var toc = doc.Body.Paragraphs.Add().AddComplexField(tocOpts);
doc.Body.Paragraphs.Last().AddSectionBreak();

// Create TC field options.
TcFieldOptions tcOptions = new TcFieldOptions(doc);

// Create random content with three headers.
var rnd = Util.NewRandom();
for (int i = 0; i < rnd.Next(2, 4); i++)
{
    // Set content for TOC.
    tcOptions.Content.Text = $"First Header {i + 1}";
    tcOptions.DisplayLevel = OutlineLevel.Level1;
    var p = doc.Body.AddParagraph().AddComplexField(tcOptions);
    var par = Util.LoremIpsumPar();
    doc.Body.AddParagraph(par);
    doc.Body.Paragraphs.Add().AddSectionBreak();
    for (int j = 0; j < rnd.Next(3, 5); j++)
    {
        // Set content for TOC.
        tcOptions.Content.Text = $"Second Header {j + 1}";
        tcOptions.DisplayLevel = OutlineLevel.Level2;
        p = doc.Body.AddParagraph().AddComplexField(tcOptions);
        par = Util.LoremIpsumPar();
        doc.Body.AddParagraph(par);
        doc.Body.Paragraphs.Add().AddSectionBreak();
        for (int k = 0; k < rnd.Next(2, 3); k++)
        {
            // Set content for TOC.
            tcOptions.Content.Text = $"Third Header {k + 1}";
            tcOptions.DisplayLevel = OutlineLevel.Level3;
            p = doc.Body.AddParagraph().AddComplexField(tcOptions);
            par = Util.LoremIpsumPar();
            doc.Body.AddParagraph(par);
        }
    }
}

// Update fields using a specific culture.
doc.UpdateFields(new GrapeCity.Documents.Word.Layout.WordLayoutSettings() { FontCollection = Util.FontCollection, Culture = CultureInfo.GetCultureInfo("en-US") });

// Save the document.
doc.Save("TCFieldOptions.docx");

    TOC Field Options

    TOC field creates a table of contents. TocFieldOptions class provides the following options:

    Option Description
    Load Loads options from a simple field or complex field.
    Save Saves options to a simple field or complex field.
    Styles Gets the collection of styles that paragraphs should be collected by the TOC field.
    TcFields Gets options to collect TC fields by the TOC field.
    SeqFields Gets options to collect SEQ fields paragraphs by the TOC field.
    PageNumbers Gets options to show page numbers in the TOC field result.
    EntryFormatting Gets options to format TOC entries in the TOC field result.
    Bookmark Sets the bookmark name that allows you to include entries only from the portion of the document marked by this bookmark.
    FlatList Sets whether all TOC entries should be on the same level.

    Refer to the following example code to add TOC field and specify its options:

    C#
    Copy Code 
    // Initialize GcWordDocument.
var doc = new GcWordDocument();

// Add page header.
var pgOptHeader = new PageFieldOptions(doc);
pgOptHeader.NumberStyle = NumberStyle.Decimal;
var pgOptBody = new PageFieldOptions(doc);

doc.Body.Sections.First.Headers[HeaderFooterType.Primary].Body.AddParagraph("Page Header - Page ").AddComplexField(pgOptHeader);

// Set TOC field options.
var tocOpts = new TocFieldOptions(doc);
tocOpts.EntryFormatting.CreateHyperlink = true;
            
// Build TOC with paragraphs that formatted only 'Heading 1' or 'Heading 2' or 'Heading 3' styles.
foreach (TocStyleLevel style in tocOpts.Styles)
{
    switch (style.Level)
    {
        case OutlineLevel.Level1:
        case OutlineLevel.Level2:
        case OutlineLevel.Level3:
            style.Collect = true;
            break;
        default:
            style.Collect = false;
            break;
    }
}

// Add TOC and a section break to the document.
var toc = doc.Body.Paragraphs.Add().AddComplexField(tocOpts);
doc.Body.Paragraphs.Last().AddSectionBreak();

// Create random content with 3 levels of headers.
var rnd = Util.NewRandom();
for (int i = 0; i < rnd.Next(2, 4); i++)
{
    var p = doc.Body.AddParagraph($"This is top-level header {i + 1}", doc.Styles[BuiltInStyleId.Heading1]);
    var par = Util.LoremIpsumPar();
    doc.Body.AddParagraph(par);
    for (int j = 0; j < rnd.Next(3, 5); j++)
    {
        p = doc.Body.AddParagraph($"This is second-level header {j + 1}", doc.Styles[BuiltInStyleId.Heading2]);
        par = Util.LoremIpsumPar();
        doc.Body.AddParagraph(par);
        for (int k = 0; k < rnd.Next(2, 3); k++)
        {
            p = doc.Body.AddParagraph($"This is third-level header {k + 1}", doc.Styles[BuiltInStyleId.Heading3]);
            par = Util.LoremIpsumPar();
            doc.Body.AddParagraph(par);
        }
    }
}

// Update fields using a specific culture.
doc.UpdateFields(new GrapeCity.Documents.Word.Layout.WordLayoutSettings() { FontCollection = Util.FontCollection, Culture = CultureInfo.GetCultureInfo("en-US") });

// Save the document.
doc.Save("TOCFieldOptions.docx");
    Note: The example codes in this topic generate random text for the document using a helper file Util.cs. To run the example codes directly, download the file from here.

     

    Limitations

    DsWord supports field type-specific options and result updating for the following field types: