Skip to end of metadata
Go to start of metadata
Contents Summary


In Microsoft Word, you can create a form by starting with a template and adding content controls, including check boxes, text boxes, date pickers, and drop-down lists. In Aspose.Words, a Structured Document Tag or content control from any document loaded into Aspose.Words is imported as a StructuredDocumentTag node. Structured document tags (SDT or content control) allow to embed customer-defined semantics as well as its behavior and appearance into a document.

StructuredDocumentTag can occur in a document in the following places:

  • Block-level - Among paragraphs and tables, as a child of a Body, HeaderFooter, Comment, Footnote or a Shape node.
  • Row-level - Among rows in a table, as a child of a Table node.
  • Cell-level - Among cells in a table row, as a child of a Row node.
  • Inline-level - Among inline content inside, as a child of a Paragraph.
  • Nested inside another StructuredDocumentTag.

Inserting Content Controls into a Document

In this version of Aspose.Words, the following types of SDT or content control can be created:

  • Checkbox
  • DropDownList
  • ComboBox
  • Date
  • BuildingBlockGallery
  • Group
  • Picture
  • RichText
  • PlainText

Below example shows how to create content control of type check box.

Below example shows how to create content control of type rich text box.

Below example shows how to create content control of type combo box.

How to update Content Controls

This section explains how to update the values of SDT or content control programmatically. Below example shows how to set the current state of check box. You can download the template file of this example from here.

Below example shows how to modify content controls of type plain text box, drop down list and picture. You can download the template file of this example from here.

How to Use Control Characters

Microsoft Word documents may contain various characters that have a special meaning. Normally they are used for formatting purposes and are not drawn in the normal mode. You can make them visible if you click the Show/Hide Formatting Marks button located on the Standard toolbar. Sometimes you may need to add or remove characters to/from the text. For instance, when obtaining text programmatically from the document, Aspose.Words preserves most of the control characters, so if you need to work with this text you should probably remove or replace the characters.

The ControlChar class is a repository for the constants that represent control characters often encountered in documents. It provides both char and string versions of the same constants. For example, string ControlChar.LineBreak and char ControlChar.LineBreakChar have the same value.

Use this class whenever you want to deal with control characters.

Below example shows how to use control characters.

Binding Content Control to Custom XML Parts

You can bind content controls with XML data (custom XML part) in Word documents. Below example shows how to bind content control to custom XML parts. 

Clear Contents of a Content Control

You can clear contents of a content control with displaying a placeholder. StructuredDocumentTag.clear() method clears contents of this structured document tag and displays a placeholder if it is defined. However, It is not possible to clear contents of a content control if it has revisions. If a content control has no placeholder, five spaces are inserted like in MS Word (except repeating sections, repeating section items, groups, check-boxes, citations). If a content control is mapped to custom XML, the referenced XML node is cleared. Following code example shows how to clear the content of content control.

Change Content Control Background and Border Colors

The StructuredDocumentTag.Color property allows you to get or set the color of content control. The color affects content control in two situations:

1) MS Word highlights the background of the content control when the mouse moves over the content control. This helps to identify the content control. The color of highlighting is a bit "softer", than the Color. For example, MS Word highlights background with the pink color, when Color is Red.
2) When you interact (editing, picking etc) with the content control, the border of content control is colored with the Color.

Below code example shows how to change the color of content control. 

How to Set Style to Format Text Typed into the Content Control

If you want to set the style of content control, you can use StructuredDocumentTag.Style or StructuredDocumentTag.StyleName properties. Below code example shows how to set the style of content control. When you type the text into content control in output document, the typed text will have style "Quote".

Note that only Linked and Character styles can be applied to the content control. An InvalidOperationException ("Cannot apply this style to the SDT") is thrown when a style that exists but is not Linked or Character style is being applied.

  • No labels