What's New in Document Solutions for Word v8

Update TOA and TA Fields

DsWord now provides APIs to work with TOA (Table of Authorities) and TA (Table of Authorities Entry) fields, making it easier to build and manage legal or reference-heavy documents programmatically.

The new ToaFieldOptions class enables developers to read and modify TOA field options, while the ToaPageNumberOptions class controls how page numbers are displayed. A CitationCategoryMap class has also been added to retrieve citation category names for more accurate categorization.

For TA fields, the new TaFieldOptions class allows reading and writing of TA field options, which define the text and page numbers or ranges for individual TOA entries. Together, these enhancements give developers full control to generate, update, and customize TOA and TA fields in Word documents.

The following code shows how to update TOA and TA fields programmatically:

// create a table of authorities entry options
TaFieldOptions ta = new TaFieldOptions(doc);
// set the category for the table of authorities entry 
ta.Category = 1;
ta.LongCitation.Text = "Anderson v. United States, 612 F.2d 1112 (9th Cir.1980)";
// create the invisible table of authorities entry field with specified options
p.AddComplexField(ta);
// add visible text to the same paragraph
p.AddRun(" Anderson v. United States");
// do the same for the other entries
ta.LongCitation.Text = "Duff v. Wilson, 69 Pa. 316 (Pa. 1871)";
p.AddComplexField(ta);
p.AddRun(", Duff v. Wilson");
ta.LongCitation.Text = "Sandstrom v. Larsen, 59 Haw. 491, 583 P.2d 971 (1978)";
p.AddComplexField(ta);
p.AddRun(" and Sandstrom v. Larsen.");
// create paragraph for the table of authorities field
p = doc.Body.AddParagraph();
// create options for the table of authorities field
ToaFieldOptions toa = new ToaFieldOptions(doc);
// set the category to include table of authorities entries
toa.EntriesCategory = 1;
// create table of authorities field with specified options
ComplexField field = p.AddComplexField(toa);
// build the table of authorities
field.Update();

Easily generate and customize legal references in Word documents with the new TOA and TA field APIs.

Help | Demo

Get List of Template Tags Defined in the Document

DsWord now provides a new API to retrieve all template tags (placeholders such as {{CustomerName}}) defined in a Data Template. Using the DataTemplate.GetTemplateTagInfos() method, developers can obtain a list of TemplateTagInfo objects that provide details such as the tag’s name, type, range, and text. This makes it easy to analyze or store placeholder information for reporting, data validation, or role-based permissions.

The following code showcases the new GetTemplateTagInfos() method in the DataTemplateclass:

// New method on the DataTemplate class:
public class DataTemplate
{ 
    // Gets the list of templates in the current document.
    List<TemplateTagInfo> GetTemplateTagInfos();
}

Quickly retrieve template tags to integrate with back-end systems or data workflows.

Help | Demo

Access Template Tags and Locations in the Exported PDF

When exporting a DsWord document to PDF, you can now mark template tag locations for accessibility, validation, or review. By setting WordLayoutSettings.MarkTemplateTagAreas = true, DsWord records the positions of template tags during layout. Developers can then use the PdfOutputSettings.MarkupTemplateTags delegate to add custom markup, such as PDF annotations, to highlight these tags on each page.

The code below showcases how to accomplish such a scenario:

// To use the API when exporting the DOCX:
// - Set MarkTemplateTagAreas to true in WordLayoutSettings, and
// - Specify your custom MarkupTemplateTags method in PdfOutputSettings.
public class MarkTagsInPDF
{
    public GcWordDocument CreateDocx()
    {
        var doc = new GcWordDocument();
        doc.Load(Path.Combine("Resources", "WordDocs", "House_Rental_Template.docx"));
        return doc;
    }

    public static WordLayoutSettings GetWordLayoutSettings()
    {
        return new WordLayoutSettings()
        {
            MarkTemplateTagAreas = true
        };
    }

    // Custom PDF output settings include a MarkupTemplateTags method
    // that adds markup annotations over Report/Data Template tags
    // present in the original DOCX.
    public static PdfOutputSettings GetPdfOutputSettings()
    {
        var settings = new PdfOutputSettings()
        {
            MarkupTemplateTags = (page, tags) =>
            {
                foreach (var tag in tags)
                {
                    foreach (var rect in tag.Areas)
                    {
                        var hilight = new TextMarkupAnnotation
                        {
                            Area = [rect],
                            Color = Color.YellowGreen,
                            MarkupType = TextMarkupType.Highlight,
                            Opacity = 0.4f,
                            RichText = $"Tag Info:<br>Name: <b>{tag?.Info?.Name}</b><br>Text: <b>{tag?.Info?.Text}</b>",
                        };

                        page.Annotations.Add(hilight);
                    }
                }
            }
        };
        return settings;
    }
}

Easily identify and highlight template tags in exported PDFs to support accessibility and review workflows.

Help | Demo

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.