How to: Add Content Controls to Word Documents

Article
02/04/2013

In document-level Word projects, you can add content controls to the document in your project at design time or at run time. In application-level Word projects, you can add content controls to any open document at run time.

Applies to: The information in this topic applies to document-level projects and application-level projects for Word 2007 and Word 2010. For more information, see Features Available by Office Application and Project Type.

This topic describes the following tasks:

Adding content controls at design time
Adding content controls at run time in a document-level project
Adding content controls at run time in an application-level project

For information about content controls, see Content Controls.

Adding Content Controls at Design Time

There are several ways to add content controls to the document in a document-level project at design time:

Add a content control from the Word Controls tab of the Toolbox.
Add a content control to your document in the same manner you would add a native content control in Word.
Drag a content control to your document from the Data Sources window. This is useful when you want to bind the control to data when the control is created. For more information, see How to: Populate Documents with Data from Objects and How to: Populate Documents with Data from a Database.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

To add a content control to a document by using the Toolbox

In the document that is hosted in the Visual Studio designer, put the cursor where you want to add the content control, or select the text that you want the content control to replace.
Open the Toolbox and click the Word Controls tab.
Add the control one of the following ways:
- Double-click a content control in the Toolbox.
  
  or
- Click a content control in the Toolbox and then press the ENTER key.
  
  or
- Drag a content control from the Toolbox to the document. The content control is added at the current selection in the document, not at the location of the mouse pointer.

Note

You cannot add a GroupContentControl by using the Toolbox. You can only add a GroupContentControl in Word, or at run time.

Note

Visual Studio does not provide a check box content control in the Toolbox for Word 2010 projects. To add a check box content control to the document, you must create a ContentControl object programmatically. For more information, see Content Controls.

To add a content control to a document in Word

In the document that is hosted in the Visual Studio designer, put the cursor where you want to add the content control, or select the text that you want the content control to replace.
On the Ribbon, click the Developer tab.

Note

If the Developer tab is not visible, you must first show it. For more information, see How to: Show the Developer Tab on the Ribbon.
In the Controls group, click the icon for the content control that you want to add.

Adding Content Controls at Run Time in a Document-Level Project

You can add content controls programmatically to your document at run time by using methods of the Controls property of the ThisDocument class in your project. Each method has three overloads that you can use to add a content control in the following ways:

Add a control at the current selection.
Add a control at a specified range.
Add a control that is based on a native content control in the document.

Dynamically created content controls are not persisted in the document when the document is closed. However, a native content control remains in the document. You can recreate a content control that is based on a native content control the next time the document is opened. For more information, see Adding Controls to Office Documents at Run Time.

Note

To add a check box content control to a document in a Word 2010 project, you must create a ContentControl object. For more information, see Content Controls.

To add a content control at the current selection

Use a ControlCollection method that has the name Add<control class> (where control class is the class name of the content control that you want to add, such as AddRichTextContentControl), and that has a single parameter for the name of the new control.

The following code example uses the ControlCollection.AddRichTextContentControl(String) method to add a new RichTextContentControl to the beginning of the document. To run this code, add the code to the ThisDocument class in your project, and call the AddRichTextControlAtSelection method from the ThisDocument_Startup event handler.

Dim richTextControl1 As Microsoft.Office.Tools.Word.RichTextContentControl

Private Sub AddRichTextControlAtSelection()
    Me.Paragraphs(1).Range.InsertParagraphBefore()
    Me.Paragraphs(1).Range.Select()
    richTextControl1 = Me.Controls.AddRichTextContentControl("richTextControl1")
    richTextControl1.PlaceholderText = "Enter your first name"
End Sub

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl1;

private void AddRichTextControlAtSelection()
{
    this.Paragraphs[1].Range.InsertParagraphBefore();
    this.Paragraphs[1].Range.Select();

    richTextControl1 = this.Controls.AddRichTextContentControl("richTextControl1");
    richTextControl1.PlaceholderText = "Enter your first name";
}

To add a content control at a specified range

Use a ControlCollection method that has the name Add<control class> (where control class is the name of the content control class that you want to add, such as AddRichTextContentControl), and that has a Microsoft.Office.Interop.Word.Range parameter.

The following code example uses the ControlCollection.AddRichTextContentControl(Range, String) method to add a new RichTextContentControl to the beginning of the document. To run this code, add the code to the ThisDocument class in your project, and call the AddRichTextControlAtRange method from the ThisDocument_Startup event handler.

Dim richTextControl2 As Microsoft.Office.Tools.Word.RichTextContentControl

Private Sub AddRichTextControlAtRange()
    Me.Paragraphs(1).Range.InsertParagraphBefore()
    richTextControl2 = Me.Controls.AddRichTextContentControl(Me.Paragraphs(1).Range, _
        "richTextControl2")
    richTextControl2.PlaceholderText = "Enter your first name"
End Sub

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl2;

private void AddRichTextControlAtRange()
{
    this.Paragraphs[1].Range.InsertParagraphBefore();

    richTextControl2 = this.Controls.AddRichTextContentControl(this.Paragraphs[1].Range,
        "richTextControl2");
    richTextControl2.PlaceholderText = "Enter your first name";
}

To add a content control that is based on a native content control

The following code example uses the ControlCollection.AddRichTextContentControl(ContentControl, String) method to create a new RichTextContentControl for every native rich text control that is in the document. To run this code, add the code to the ThisDocument class in your project, and call the CreateRichTextControlsFromNativeControls method from the ThisDocument_Startup event handler.

Private richTextControls As New System.Collections.Generic.List _
        (Of Microsoft.Office.Tools.Word.RichTextContentControl)

Private Sub CreateRichTextControlsFromNativeControls()
    If Me.ContentControls.Count <= 0 Then
        Return
    End If

    Dim count As Integer = 0
    For Each nativeControl As Word.ContentControl In Me.ContentControls
        If nativeControl.Type = Word.WdContentControlType.wdContentControlRichText Then
            count += 1
            Dim tempControl As Microsoft.Office.Tools.Word.RichTextContentControl = _
                Me.Controls.AddRichTextContentControl(nativeControl, _
                "VSTORichTextContentControl" + count.ToString())
            richTextControls.Add(tempControl)
        End If
    Next nativeControl
End Sub

private System.Collections.Generic.List
    <Microsoft.Office.Tools.Word.RichTextContentControl> richTextControls;

private void CreateRichTextControlsFromNativeControls()
{
    if (this.ContentControls.Count <= 0)
        return;

    richTextControls = new System.Collections.Generic.List
        <Microsoft.Office.Tools.Word.RichTextContentControl>();
    int count = 0;

    foreach (Word.ContentControl nativeControl in this.ContentControls)
    {
        if (nativeControl.Type ==
            Microsoft.Office.Interop.Word.WdContentControlType.wdContentControlRichText)
        {
            count++;
            Microsoft.Office.Tools.Word.RichTextContentControl tempControl =
                this.Controls.AddRichTextContentControl(nativeControl,
                "VSTORichTextControl" + count.ToString());
            richTextControls.Add(tempControl);
        }
    }
}

Adding Content Controls at Run Time in an Application-Level Project

You can add content controls programmatically to any open document at run time by using an application-level add-in. To do this, generate a Document host item that is based on an open document, and then use methods of the Controls property of this host item. Each method has three overloads that you can use to add a content control in the following ways:

Add a control at the current selection.
Add a control at a specified range.
Add a control that is based on a native content control in the document.

For more information about generating host items in application-level projects, see Extending Word Documents and Excel Workbooks in Application-Level Add-ins at Run Time.

Note

To add a check box content control to a document in a Word 2010 project, you must create a ContentControl object. For more information, see Content Controls.

To add a content control at the current selection

The following code example uses the ControlCollection.AddRichTextContentControl(String) method to add a new RichTextContentControl to the beginning of the active document. To run this code, add the code to the ThisAddIn class in your project, and call the AddRichTextControlAtSelection method from the ThisAddIn_Startup event handler.

Dim richTextControl1 As Microsoft.Office.Tools.Word.RichTextContentControl

Private Sub AddRichTextControlAtSelection()
    Dim currentDocument As Word.Document = Me.Application.ActiveDocument
    currentDocument.Paragraphs(1).Range.InsertParagraphBefore()
    currentDocument.Paragraphs(1).Range.Select()

    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim extendedDocument As Document = Globals.Factory.GetVstoObject(currentDocument)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim extendedDocument As Document = currentDocument.GetVstoObject()

    richTextControl1 = extendedDocument.Controls.AddRichTextContentControl("richTextControl1")
    richTextControl1.PlaceholderText = "Enter your first name"
End Sub

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl1;

private void AddRichTextControlAtSelection()
{
    Word.Document currentDocument = this.Application.ActiveDocument;
    currentDocument.Paragraphs[1].Range.InsertParagraphBefore();
    currentDocument.Paragraphs[1].Range.Select();

    // Use the following line of code in projects that target the .NET Framework 4.
    Document extendedDocument = Globals.Factory.GetVstoObject(currentDocument);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // Document extendedDocument = currentDocument.GetVstoObject();

    richTextControl1 = extendedDocument.Controls.AddRichTextContentControl("richTextControl1");
    richTextControl1.PlaceholderText = "Enter your first name";
}

To add a content control at a specified range

The following code example uses the ControlCollection.AddRichTextContentControl(Range, String) method to add a new RichTextContentControl to the beginning of the active document. To run this code, add the code to the ThisAddIn class in your project, and call the AddRichTextControlAtRange method from the ThisAddIn_Startup event handler.

Dim richTextControl2 As Microsoft.Office.Tools.Word.RichTextContentControl

Private Sub AddRichTextControlAtRange()
    Dim currentDocument As Word.Document = Me.Application.ActiveDocument
    currentDocument.Paragraphs(1).Range.InsertParagraphBefore()

    ' Use the following line of code in projects that target the .NET Framework 4.
    Dim extendedDocument As Document = Globals.Factory.GetVstoObject(currentDocument)

    ' In projects that target the .NET Framework 3.5, use the following line of code.
    ' Dim extendedDocument As Document = currentDocument.GetVstoObject()

    richTextControl2 = extendedDocument.Controls.AddRichTextContentControl( _
        extendedDocument.Paragraphs(1).Range, "richTextControl2")
    richTextControl2.PlaceholderText = "Enter your first name"
End Sub

private Microsoft.Office.Tools.Word.RichTextContentControl richTextControl2;

private void AddRichTextControlAtRange()
{
    Word.Document currentDocument = this.Application.ActiveDocument;
    currentDocument.Paragraphs[1].Range.InsertParagraphBefore();

    // Use the following line of code in projects that target the .NET Framework 4.
    Document extendedDocument = Globals.Factory.GetVstoObject(currentDocument);

    // In projects that target the .NET Framework 3.5, use the following line of code.
    // Document extendedDocument = currentDocument.GetVstoObject();

    richTextControl2 = extendedDocument.Controls.AddRichTextContentControl(
        currentDocument.Paragraphs[1].Range, "richTextControl2");
    richTextControl2.PlaceholderText = "Enter your first name";
}

To add a content control that is based on a native content control

The following code example uses the ControlCollection.AddRichTextContentControl(ContentControl, String) method to create a new RichTextContentControl for every native rich text control that is in a document, after the document is opened. To run this code, add the code to the ThisAddIn class in your project.

Private richTextControls As New System.Collections.Generic.List _
    (Of Microsoft.Office.Tools.Word.RichTextContentControl)

Private Sub Application_DocumentOpen(ByVal Doc As Microsoft.Office.Interop.Word.Document) _
    Handles Application.DocumentOpen

    If Doc.ContentControls.Count > 0 Then

        ' Use the following line of code in projects that target the .NET Framework 4.
        Dim extendedDocument As Document = Globals.Factory.GetVstoObject(Doc)

        ' In projects that target the .NET Framework 3.5, use the following line of code.
        ' Dim extendedDocument As Document = Doc.GetVstoObject()

        Dim count As Integer = 0
        For Each nativeControl As Word.ContentControl In Doc.ContentControls
            If nativeControl.Type = Word.WdContentControlType.wdContentControlRichText Then
                count += 1
                Dim tempControl As Microsoft.Office.Tools.Word.RichTextContentControl = _
                    extendedDocument.Controls.AddRichTextContentControl(nativeControl, _
                    "VSTORichTextContentControl" + count.ToString())
                richTextControls.Add(tempControl)
            End If
        Next nativeControl
    End If
End Sub

private System.Collections.Generic.List
    <Microsoft.Office.Tools.Word.RichTextContentControl> richTextControls;

private void Application_DocumentOpen(Microsoft.Office.Interop.Word.Document Doc)
{
    if (Doc.ContentControls.Count > 0)
    {
        // Use the following line of code in projects that target the .NET Framework 4.
        Document extendedDocument = Globals.Factory.GetVstoObject(Doc);

        // In projects that target the .NET Framework 3.5, use the following line of code.
        // Document extendedDocument = Doc.GetVstoObject();

        richTextControls = new System.Collections.Generic.List
            <Microsoft.Office.Tools.Word.RichTextContentControl>();
        int count = 0;

        foreach (Word.ContentControl nativeControl in Doc.ContentControls)
        {
            if (nativeControl.Type ==
                Microsoft.Office.Interop.Word.WdContentControlType.wdContentControlRichText)
            {
                count++;
                Microsoft.Office.Tools.Word.RichTextContentControl tempControl =
                    extendedDocument.Controls.AddRichTextContentControl(nativeControl,
                    "VSTORichTextControl" + count.ToString());
                richTextControls.Add(tempControl);
            }
        }
    }
}

For C#, you must also attach the Application_DocumentOpen event handler to the DocumentOpen event.

this.Application.DocumentOpen +=
    new Word.ApplicationEvents4_DocumentOpenEventHandler(Application_DocumentOpen);

How to: Add Content Controls to Word Documents

Adding Content Controls at Design Time

To add a content control to a document by using the Toolbox

To add a content control to a document in Word

Adding Content Controls at Run Time in a Document-Level Project

To add a content control at the current selection

To add a content control at a specified range

To add a content control that is based on a native content control

Adding Content Controls at Run Time in an Application-Level Project

To add a content control at the current selection

To add a content control at a specified range

To add a content control that is based on a native content control

See Also

Concepts

Other Resources

Additional resources