Content Controls

Forms and templates created in MS Word can contain content controls. When your users open such documents in the Document Editor, it matters how content controls appear after a DOCX document is loaded, how your code works with them and what is written back when the document is saved.

What Content Controls Are

Content controls are the form elements of MS Word documents, such as text boxes, check boxes, drop-down lists, combo boxes and date pickers. They replaced the older legacy form fields of MS Word and are stored in DOCX documents.

TX Text Control has no content control object in the Document Editor. When it loads a document, it converts content controls into its own fields, and when it saves a DOCX document, it writes them back as content controls.

Content Controls in Loaded Documents

When a DOCX document with content controls is loaded into a visual TX Text Control such as the Document Editor, the content controls are shown as form fields by default. Each type becomes the matching form field:

Users fill them out and edit them like any other form field, and your code works with them through the form field API described on Form Fields.

The load settings decide the conversion. The applicationFieldFormat setting of LoadSettings takes a value of ApplicationFieldFormat:

Application fields are described on Fields.

Read the Converted Fields

The following view loads a DOCX document with content controls, lists the form fields they became and saves the document as DOCX again. Save a document named contentcontrols.docx with content controls in the Documents folder of the project from the ASP.NET Core tutorial, and replace the content of Views/Home/Index.cshtml:

@using TXTextControl.Web.MVC

@Html.TXTextControl().TextControl().LoadText(
    "Documents/contentcontrols.docx",
    TXTextControl.Web.StreamType.WordprocessingML).Render()

<input type="button" onclick="listFormFields()" value="List Form Fields" />
<input type="button" onclick="saveAsDocx()" value="Save as DOCX" />

<script>
    function listFormFields() {
        TXTextControl.getTextFieldsByType(TXTextControl.TextFieldType.FormFields, function (fields) {
            fields.forEach(function (field) {
                console.log(field.name + ": " + field.text);
            });
        }, function (error) {
            console.log(error.msg);
        });
    }

    function saveAsDocx() {
        TXTextControl.saveDocument(TXTextControl.StreamType.WordprocessingML, function (result) {
            // result.data contains the DOCX document as a Base64 string for your server
            console.log(result.data.length + " characters of DOCX data");
        });
    }
</script>

• LoadText loads the DOCX document when the view is rendered.
• getTextFieldsByType with FormFields from TextFieldType passes the names and texts of all form fields, including those that were content controls.
• saveDocument with WordprocessingML saves the document as DOCX.

Click List Form Fields and open the browser console to see the fields of the document.

Content Controls in Saved Documents

Which kind of field a form field becomes depends on the format you save in:

A form that users fill out in the editor therefore opens in MS Word with content controls again when you save it as DOCX. The Document Editor uses the Core engine, which doesn't save DOC documents.

Content Controls on the Server

On the server, the TXTextControl.DocumentServer.Fields namespace has classes that read and change the properties of content controls, such as their title and tag, which the form fields of the editor don't expose. They work with documents loaded with the MSWord application field format and wrap an application field of ServerTextControl: ContentControlFieldAdapter is the base class, with PlainTextContentControl, RichTextContentControl, CheckBoxContentControl, ComboBoxContentControl, DropDownListContentControl and DateContentControl for the types. Content Controls in Document Processing describes them.

The blog article Working with Content Controls in MS Word Documents using TX Text Control in C# reads content controls with these classes.

Next Steps

• Form Fields: work with the converted content controls.
• Fields: application fields and other fields.
• Loading and Saving Documents: load and save DOCX documents.