What's New in Document Solutions for Word v8

Features to Update Fields

In the v8.0 release, DsWord added support for working with and updating Fields in word documents. In the v8.1 release, we support the same with additional fields -

• INDEX Field: Creates an index, which is a list of terms or topics that are mentioned in a document.
• XE Field: Marks text for inclusion in an index.

These can be utilized via the UpdateFields and Update methods.

The UpdateFields method of the GcWordDocument and RangeBase classes enables users to update all fields in the document or all fields that support updating in the range. Meanwhile, the Update method of the ComplexField and SimpleField classes allows users to update the field results.

DsWord also supports strong-typed access to the options of the INDEX and XE field types to read and write arguments and switches using the IndexFieldOptions and XeFieldOptions classes. These strong-typed field types also support PDF export. 

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

for (int i = 0; i < NPARS; ++i)
{
      var par = doc.Body.Paragraphs.Add();
      var txt = Util.LoremIpsumPar();
      var words = txt.Split([' ', ',', '.'], 2);
      if (words.Length != 2)
      throw new Exception("Unexpected");
      var word = words[0];
      var xe = new XeFieldOptions(doc);
      xe.Entry.Content.Text = word;
      par.AddComplexField(xe);
      par.AddRun(txt);
}
// Add new section for the index:
doc.Body.Paragraphs.Last.AddSectionBreak();
var p = doc.Body.Paragraphs.Add(doc.Styles[BuiltInStyleId.Index1]);
// Set up INDEX field options:
var index = new IndexFieldOptions(doc);
// Two column layout:
index.Columns = 2;
// Use headings for index entries:
index.Heading = "A";
// Set any additional options as needed,
// then create the INDEX field with the specified options:
ComplexField field = p.AddComplexField(index);
// Update the index field with a specific culture:
field.Update(new GrapeCity.Documents.Word.Layout.WordLayoutSettings() 
{ FontCollection = Util.FontCollection, Culture = CultureInfo.GetCultureInfo("en-US") 
});

Help | Demo

Enhancements When Working with Fields

Fields in Microsoft Word act as dynamic placeholders for data that can automatically update based on certain conditions, eliminating the need for manual updates and helping create consistently formatted, professional documents. Fields are not only useful for displaying dynamic data but can also be customized and controlled by adjusting their arguments (parameters) and switches (modifiers) to modify their behavior and output.

In the v8.0 release, DsWord has added support for working with and updating the following fields:

• PAGE - The PAGE field retrieves the number of the current page.
• PAGEREF - The PAGEREF field inserts the number of the page containing the bookmark for a cross-reference.
• SECTION - The SECTION field retrieves the number of the current section.
• SECTIONPAGES - The SECTIONPAGES field retrieves the number of the current page within the current section
• SEQ - The SEQ field sequentially numbers chapters, tables, figures, and other user-defined lists of items in a document.
• TC -  The TC field defines the text and page number for a table of contents (including a table of figures) entry, which is used by a TOC field.
• TOC - The TOC field builds a table of contents (which can also be a table of figures) using the entries specified by TC fields, their heading levels, specified styles and inserts that table at this place in the document.

Each of the fields listed above has a corresponding …FieldOptions class (living in the GrapeCity.Documents.Word.Fields namespace) that provides strong typed access to read and write arguments and switches of specific field type. The FieldFormatOptions class represents a base class for ...FieldOptions classes that supports the formatting properties.

To update (recalculate) the fields, use the new GcWordDocument.UpdateFields() method, or the Update() method on a specific field. This allows you to include the updated field results in the DOCX or in export to PDF or images.

Have a look on the detailed API for each Field type in the links for each field above. 

Following code helps to add TOC to a Word Document at the second page using TOCFieldOptions class.

var doc = new GcWordDocument();
doc.Load("Annual Financial Report.docx");
var para6 = doc.Body.Paragraphs[6];
var newSection = para6.AddSectionBreak();
var tocPara = newSection.AddParagraph();
var options = new TocFieldOptions(doc);
options.EntryFormatting.CreateHyperlink = true;
// build TOC with paragraphs that formatted only 'Heading 1' or 'Heading 2' or 'Heading 3' styles
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;
    }
}
var toc = tocPara.AddComplexField(options);
toc.Update();
doc.Save("ReportWithTOC.docx");
using (var layout = new GcWordLayout(doc))
{
    // save the whole document as PDF
    layout.SaveAsPdf("ReportWithTOC.pdf", null, new PdfOutputSettings() { CompressionLevel = CompressionLevel.Fastest });
}

Help | Demo

DsWordLayout package is now merged into DsWord package

From v8 onwards, the DsWordLayout package (that enables saving Word documents to PDF or images) has been merged to DsWord package. The changes are backwards compatible, any user code will continue to work in v8.0, the only change is the need to remove references to DsWordLayout from user projects as it is no longer required.