Content Controls (Structured Document Tags)

Content Controls (also called Structured Document Tags) allow you to customize a document. GemBox.Document supports two kinds of Content Controls; you can use BlockContentControl as a block element, and InlineContentControl as an inline element.

The ContentControlType enumeration contains a list of Content Control types supported through GemBox.Document's API. Each Content Control element can be customized using the ContentControlProperties class.

The following example shows how you can create various Content Controls and change their properties, in C# and VB.NET.

Word document with Content Controls or Structured Document Tags
Screenshot of Word file with Content Controls
View on GitHub 
using GemBox.Document;
using GemBox.Document.CustomMarkups;

class Program
{
    static void Main()
    {
        // If using the Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY");

        var document = new DocumentModel();

        var section = new Section(document);
        document.Sections.Add(section);

        // Create locked Rich Text Content Control.
        var richTextControl = new BlockContentControl(document, ContentControlType.RichText,
            new Paragraph(document, "This text is inside Rich Text Content Control."),
            new Paragraph(document, "It cannot be deleted or edited."));
        richTextControl.Properties.LockEditing = true;
        richTextControl.Properties.LockDeleting = true;
        section.Blocks.Add(richTextControl);

        // Create named Plain Text Content Control.
        var plainTextControl = new BlockContentControl(document, ContentControlType.PlainText,
            new Paragraph(document, "Plain Text Content Control with tag and title."));
        plainTextControl.Properties.Tag = "Plain Text Name";
        plainTextControl.Properties.Title = "Plain Text Title";
        section.Blocks.Add(plainTextControl);

        // Create CheckBox Content Control.
        var checkBoxControl = new InlineContentControl(document, ContentControlType.CheckBox,
           new Run(document, "☒") { CharacterFormat = { FontName = "MS Gothic" } });
        checkBoxControl.Properties.Checked = true;

        // Create ComboBox Content Control.
        var comboBoxControl = new InlineContentControl(document, ContentControlType.ComboBox,
            new Run(document, "<Select GemBox Component>"));
        comboBoxControl.Properties.ListItems.Add(new ContentControlListItem("<Select GemBox Component>", "NONE"));
        comboBoxControl.Properties.ListItems.Add(new ContentControlListItem("GemBox.Spreadsheet", "GBS"));
        comboBoxControl.Properties.ListItems.Add(new ContentControlListItem("GemBox.Document", "GBD"));
        comboBoxControl.Properties.ListItems.Add(new ContentControlListItem("GemBox.Pdf", "GBA"));
        comboBoxControl.Properties.ListItems.Add(new ContentControlListItem("GemBox.Presentation", "GBP"));
        comboBoxControl.Properties.ListItems.Add(new ContentControlListItem("GemBox.Email", "GBE"));
        comboBoxControl.Properties.ListItems.Add(new ContentControlListItem("GemBox.Imaging", "GBI"));

        section.Blocks.Add(new Paragraph(document,
            checkBoxControl,
            new SpecialCharacter(document, SpecialCharacterType.LineBreak),
            comboBoxControl));

        document.Save("Content Controls.docx");
    }
}
Imports GemBox.Document
Imports GemBox.Document.CustomMarkups

Module Program

    Sub Main()

        ' If using the Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY")

        Dim document As New DocumentModel()

        Dim section As New Section(document)
        document.Sections.Add(section)

        ' Create locked Rich Text Content Control.
        Dim richTextControl As New BlockContentControl(document, ContentControlType.RichText,
            New Paragraph(document, "This text is inside Rich Text Content Control."),
            New Paragraph(document, "It cannot be deleted or edited."))
        richTextControl.Properties.LockEditing = True
        richTextControl.Properties.LockDeleting = True
        section.Blocks.Add(richTextControl)

        ' Create named Plain Text Content Control.
        Dim plainTextControl As New BlockContentControl(document, ContentControlType.PlainText,
            New Paragraph(document, "Plain Text Content Control with tag and title."))
        plainTextControl.Properties.Tag = "Plain Text Name"
        plainTextControl.Properties.Title = "Plain Text Title"
        section.Blocks.Add(plainTextControl)

        ' Create CheckBox Content Control.
        Dim checkBoxControl As New InlineContentControl(document, ContentControlType.CheckBox,
           New Run(document, "☒") With {.CharacterFormat = New CharacterFormat() With {.FontName = "MS Gothic"}})
        checkBoxControl.Properties.Checked = True

        ' Create ComboBox Content Control.
        Dim comboBoxControl As New InlineContentControl(document, ContentControlType.ComboBox,
            New Run(document, "<Select GemBox Component>"))
        comboBoxControl.Properties.ListItems.Add(New ContentControlListItem("<Select GemBox Component>", "NONE"))
        comboBoxControl.Properties.ListItems.Add(New ContentControlListItem("GemBox.Spreadsheet", "GBS"))
        comboBoxControl.Properties.ListItems.Add(New ContentControlListItem("GemBox.Document", "GBD"))
        comboBoxControl.Properties.ListItems.Add(New ContentControlListItem("GemBox.Pdf", "GBA"))
        comboBoxControl.Properties.ListItems.Add(New ContentControlListItem("GemBox.Presentation", "GBP"))
        comboBoxControl.Properties.ListItems.Add(New ContentControlListItem("GemBox.Email", "GBE"))
        comboBoxControl.Properties.ListItems.Add(New ContentControlListItem("GemBox.Imaging", "GBI"))

        section.Blocks.Add(New Paragraph(document,
            checkBoxControl,
            New SpecialCharacter(document, SpecialCharacterType.LineBreak),
            comboBoxControl))

        document.Save("Content Controls.docx")

    End Sub
End Module

Content Controls with XML Mapping

Content Controls can be mapped to XML nodes from DocumentModel.CustomXmlParts.

With GemBox.Document you can update the values separately in mapped XML (CustomXmlPart.Data) and the content of Content Control (BlockContentControl.Blocks or InlineContentControl.Inlines).

The following example shows how you can update the Content Controls elements with the values from the mapped CustomXmlPart using the IContentControl.Update method.

Word document with updated Content Controls
Screenshot of Word file with updated Content Controls
View on GitHub 
using System;
using System.Linq;
using System.Text;
using GemBox.Document;
using GemBox.Document.CustomMarkups;

class Program
{
    static void Main()
    {
        // If using the Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY");

        var document = DocumentModel.Load("%#XmlMapping.docx%");

        // Edit mapped XML part.
        document.CustomXmlParts[0].Data = Encoding.UTF8.GetBytes(
@"<?xml version=""1.0"" encoding=""UTF-8"" standalone=""yes""?>
<customer>
    <firstName>Jane</firstName>
    <lastName>Doe</lastName>
    <birthday>2010-01-01T00:00:00</birthday>
    <married>true</married>
</customer>");

        // Update Content Controls inlines or blocks based on the values from mapped XML part.
        foreach (var contentControl in document.GetChildElements(true).OfType<IContentControl>())
            contentControl.Update();

        document.Save("Updated ContentControls.%OutputFileType%");
    }
}
Imports System
Imports System.Linq
Imports System.Text
Imports GemBox.Document
Imports GemBox.Document.CustomMarkups

Module Program

    Sub Main()

        ' If using the Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY")

        Dim document = DocumentModel.Load("%#XmlMapping.docx%")

        ' Edit mapped XML part.
        document.CustomXmlParts(0).Data = Encoding.UTF8.GetBytes(
"<?xml version=""1.0"" encoding=""UTF-8"" standalone=""yes""?>
<customer>
    <firstName>Jane</firstName>
    <lastName>Doe</lastName>
    <birthday>2010-01-01T00:00:00</birthday>
    <married>true</married>
</customer>")

        ' Update Content Controls inlines or blocks based on the values from mapped XML part.
        For Each contentControl In document.GetChildElements(True).OfType(Of IContentControl)()
            contentControl.Update()
        Next

        document.Save("Updated ContentControls.%OutputFileType%")

    End Sub
End Module

The following example shows how you can update the CustomXmlPart source with the values from the mapped Content Controls elements using the IContentControl.UpdateSource method.

Word document with updated XML Mapping
Screenshot of Word file with updated XML Mapping
View on GitHub 
using System;
using System.Linq;
using System.Text;
using GemBox.Document;
using GemBox.Document.CustomMarkups;

class Program
{
    static void Main()
    {
        // If using the Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY");

        var document = DocumentModel.Load("%#XmlMapping.docx%");

        // Edit Content Controls.
        foreach (var contentControl in document.GetChildElements(true).OfType<IContentControl>())
        {
            switch (contentControl.Properties.Title)
            {
                case "FirstName":
                    contentControl.Content.LoadText("Joe");
                    break;
                case "LastName":
                    contentControl.Content.LoadText("Smith");
                    break;
                case "Birthday":
                    contentControl.Properties.Date = new DateTime(2002, 2, 2);
                    break;
                case "Married":
                    contentControl.Properties.Checked = true;
                    break;
            }

            // Update mapped XML part based on the content from Content Control.
            contentControl.UpdateSource();
        }

        document.Save("Updated XmlMapping.%OutputFileType%");
    }
}
Imports System
Imports System.Linq
Imports System.Text
Imports GemBox.Document
Imports GemBox.Document.CustomMarkups

Module Program

    Sub Main()

        ' If using the Professional version, put your serial key below.
        ComponentInfo.SetLicense("FREE-LIMITED-KEY")

        Dim document = DocumentModel.Load("%#XmlMapping.docx%")

        ' Edit Content Controls.
        For Each contentControl In document.GetChildElements(True).OfType(Of IContentControl)()
            Select Case contentControl.Properties.Title
                Case "FirstName"
                    contentControl.Content.LoadText("Joe")
                Case "LastName"
                    contentControl.Content.LoadText("Smith")
                Case "Birthday"
                    contentControl.Properties.Date = New DateTime(2002, 2, 2)
                Case "Married"
                    contentControl.Properties.Checked = True
            End Select

            ' Update mapped XML part based on the content from Content Control.
            contentControl.UpdateSource()
        Next

        document.Save("Updated XmlMapping.%OutputFileType%")

    End Sub
End Module

See also

Convert Word to or from HTML in C# / VB.NET applications

Convert Word to or from HTML in C# / VB.NET applications

Next steps

GemBox.Document is a .NET component that enables you to read, write, edit, convert, and print document files from your .NET applications using one simple API. How about testing it today?

Download Buy
Published: July 4, 2019 | Modified: December 19, 2022 | Author: Marek Turis