Content Controls

Forms that are built in MS Word with content controls, such as text boxes, check boxes, drop-down lists and date pickers, reach the server as DOCX files. How you load them decides what TX Text Control makes of them: form fields with values that are easy to read and set, or application fields that give access to Word-specific settings such as title and tag. You read and fill such forms on the server and create content controls in code.

In the Document Editor, users fill out the same forms, as Content Controls in the Document Editor section describes. Fields in general are covered in Fields. To try an example, replace the content of Program.cs of a console application with it.

What Content Controls Are

Content controls are the controls of MS Word for templates and forms, available since MS Word 2007. They replace the older legacy form fields, and TX Text Control supports both. The types are rich text, plain text, picture, combo box, drop-down list, check box and date.

Content controls are stored in DOCX documents. When a form is loaded, LoadSettings.ApplicationFieldFormat decides what they become:

Form fields are saved and loaded with the TX Text Control format, DOC, DOCX and RTF. Of the MS Word formats, only DOCX carries content controls; the MS Word 97-2003 format doesn't support them.

Read the Values of a DOCX Form

To read a filled form, load it as form fields and check the type of each field. The following program prints the value of every form field of Documents/form.docx:

using TXTextControl;

LoadSettings loadSettings = new LoadSettings()
{
    // Content controls and legacy form fields become TX Text Control form fields
    ApplicationFieldFormat = ApplicationFieldFormat.MSWordTXFormFields
};

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();
    tx.Load("Documents/form.docx", StreamType.WordprocessingML, loadSettings);

    foreach (FormField field in tx.FormFields)
    {
        switch (field)
        {
            case CheckFormField checkBox:
                Console.WriteLine($"{checkBox.Name}: check box, {checkBox.Checked}");
                break;

            case DateFormField dateField:
                Console.WriteLine($"{dateField.Name}: date, {dateField.Date?.ToShortDateString() ?? "(empty)"}");
                break;

            case SelectionFormField selectionField:
                string selected = selectionField.SelectedIndex >= 0
                    ? selectionField.Items[selectionField.SelectedIndex]
                    : "(nothing selected)";
                Console.WriteLine($"{selectionField.Name}: selection, {selected}");
                break;

            case TextFormField textField:
                Console.WriteLine($"{textField.Name}: text, {textField.Text}");
                break;
        }
    }
}

The code works as follows:

• Each FormField is an object of a derived class, and the switch statement handles each type.
• CheckFormField.Checked is true for a checked check box.
• DateFormField.Date is null when no date has been entered.
• A SelectionFormField represents a combo box or a drop-down list. SelectedIndex is -1 when nothing is selected, and Items contains the entries.
• A TextFormField is a text box whose value is its Text.

The blog article How to Import and Read Form Fields from DOCX Documents in .NET on Linux reads forms the same way with the Core engine.

Fill a DOCX Form on the Server

Filling a form works the other way around: set the values of the form fields and save the document as DOCX. The following program checks all check boxes, sets the dates to today and fills the text box named "CustomerName":

using TXTextControl;

LoadSettings loadSettings = new LoadSettings()
{
    ApplicationFieldFormat = ApplicationFieldFormat.MSWordTXFormFields
};

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();
    tx.Load("Documents/form.docx", StreamType.WordprocessingML, loadSettings);

    foreach (FormField field in tx.FormFields)
    {
        switch (field)
        {
            case CheckFormField checkBox:
                checkBox.Checked = true;
                break;

            case DateFormField dateField:
                dateField.Date = DateTime.Today;
                break;

            case TextFormField textField when textField.Name == "CustomerName":
                textField.Text = "Acme Corporation";
                break;
        }
    }

    // Form fields are saved as content controls in DOCX
    tx.Save("form-filled.docx", StreamType.WordprocessingML);
}

To send the filled form as PDF instead, save it with StreamType.AdobePDF: the form fields become PDF form fields, or they're replaced with their values, as the blog article Programmatically Fill, Flatten, and Export DOCX Form Templates to PDF in C# .NET shows. PDF Forms covers forms in PDF documents.

Create Content Controls in Code

The TXTextControl.DocumentServer.Fields namespace has an adapter class for the rich text, plain text, check box, combo box, drop-down list and date content controls. An adapter wraps an application field and gives you typed access to the content control, so you don't have to know its Office Open XML code. To create a content control, create the adapter, set its properties and add its ApplicationField at the input position:

using TXTextControl;
using TXTextControl.DocumentServer.Fields;

using (ServerTextControl tx = new ServerTextControl())
{
    tx.Create();

    // A table with a label column and a column for the content controls
    tx.Tables.Add(3, 2, 10);
    Table table = tx.Tables.GetItem(10);

    table.Cells.GetItem(1, 1).Text = "Customer name";
    table.Cells.GetItem(2, 1).Text = "Invoice date";
    table.Cells.GetItem(3, 1).Text = "Terms accepted";

    PlainTextContentControl customerName = new PlainTextContentControl()
    {
        Title = "Customer name",
        Tag = "CustomerName",
        Text = "Acme Corporation"
    };

    // Selection positions start at 0, TableCell.Start at 1
    tx.Select(table.Cells.GetItem(1, 2).Start - 1, 0);
    tx.ApplicationFields.Add(customerName.ApplicationField);

    DateContentControl invoiceDate = new DateContentControl()
    {
        Title = "Invoice date",
        Tag = "InvoiceDate",
        Date = new DateTime(2025, 5, 27)
    };

    tx.Select(table.Cells.GetItem(2, 2).Start - 1, 0);
    tx.ApplicationFields.Add(invoiceDate.ApplicationField);

    CheckBoxContentControl termsAccepted = new CheckBoxContentControl()
    {
        Title = "Terms accepted",
        Tag = "TermsAccepted",
        Checked = true
    };

    tx.Select(table.Cells.GetItem(3, 2).Start - 1, 0);
    tx.ApplicationFields.Add(termsAccepted.ApplicationField);

    tx.Save("form.docx", StreamType.WordprocessingML);
}

The code works as follows:

• Select with the start position of a cell and a length of 0 puts the input position into the cell. TableCell.Start is one-based, so 1 is subtracted.
• Each adapter has a Title and a Tag, the title and the tag of the content control in the DOCX document.
• ApplicationFieldCollection.Add inserts the content control at the input position.

The properties of the base class ContentControlFieldAdapter:

The derived classes add the value of their type:

To read the title and tag of the content controls in an existing document, load it with ApplicationFieldFormat.MSWord and pass each application field to the constructor of the adapter class of its type. The blog article Working with Content Controls in MS Word Documents using TX Text Control in C# shows a complete example.

Merge Data Into Forms

A form template can also be filled with data by a mail merge. MailMerge.FormFieldMergeType decides whether form fields keep their controls with preselected values or are replaced with the values; Merge Fields describes the options.

Next Steps

• Form Fields: create forms in code, check their values and flatten them.
• Fields: the other kinds of fields and the field adapters.
• Merge Fields: fill form fields with data in a mail merge.
• PDF Forms: create and process PDF forms.
• Content Controls in the Document Editor: let users fill out forms in the browser.