Content Controls
Overview
This guide shows how to insert a content control into a Word document and read it back with Aspose.Words FOSS for Java. A content control, called a structured document tag or SDT, marks a region of a Word document as a form field or a typed block of content. DocumentBuilder.insertStructuredDocumentTag inserts one of a given SdtType and returns a StructuredDocumentTag, which has a title, a tag and content of its own. The example inserts a plain text control, gives it a title and a tag, puts text in it and reads the control back from the saved file. It was compiled and run against the published package on Java 8, 17 and 21.
Prerequisites
| Requirement | Detail |
|---|---|
| Java | 8 or later |
| Dependency | The package from Installation |
| Import | import com.aspose.words.*; |
| Code | The examples are statements. Put them in a method that declares throws Exception. |
Insert a Plain Text Content Control
Call insertStructuredDocumentTag(SdtType.PLAIN_TEXT) and set setTitle and setTag. The control starts with placeholder content; the example removes it with removeAllChildren, appends a Run with the real text and calls isShowingPlaceholderText(false), so that Word treats the text as real content and not as placeholder text. After saving and reloading, the document had 1 content control with the title Customer name, the tag customer-name, the type plain text and the text Acme Corp, and it no longer showed placeholder text.
import com.aspose.words.*;
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Name: ");
StructuredDocumentTag tag = builder.insertStructuredDocumentTag(SdtType.PLAIN_TEXT);
tag.setTitle("Customer name");
tag.setTag("customer-name");
tag.removeAllChildren();
tag.appendChild(new Run(doc, "Acme Corp"));
tag.isShowingPlaceholderText(false);
doc.save("form.docx");
Document reloaded = new Document("form.docx");
NodeCollection tags = reloaded.getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true);
System.out.println("Content controls: " + tags.getCount());
StructuredDocumentTag saved = (StructuredDocumentTag) tags.get(0);
System.out.println("Title: " + saved.getTitle());
System.out.println("Tag: " + saved.getTag());
System.out.println("Type is plain text: " + (saved.getSdtType() == SdtType.PLAIN_TEXT));
System.out.println("Text: " + saved.getText().trim());
System.out.println("Shows placeholder text: " + saved.isShowingPlaceholderText());The program printed:
Content controls: 1
Title: Customer name
Tag: customer-name
Type is plain text: true
Text: Acme Corp
Shows placeholder text: falseTips and Best Practices
- The title is the friendly name that Word shows; the tag is for your code to find the control.
- Find controls with
getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true). SdtTypehas other types, for exampleDROP_DOWN_LIST,DATEandCHECKBOX; this page ran onlyPLAIN_TEXT.
Common Issues
| Issue | Cause | Fix |
|---|---|---|
| The compiler reports cannot find symbol for Document. | The com.aspose.words package is not imported. | Add import com.aspose.words.*;. |
| The compiler reports an unreported exception. | The Document constructors, Document.save and some other methods declare throws Exception. | Declare it on the calling method or catch it. |
| The control still shows placeholder text. | A new control starts with placeholder content and is flagged as showing it; the flag stays after you append text. | Remove the children, append your own text and call isShowingPlaceholderText(false), as in the example. |
appendChild throws an IllegalArgumentException. | The control is block level, as it is when it is the first thing in an empty document, so a Run cannot be its child. | Write some text with the builder first, as the example does, so that the control is inline. |
FAQ
What is the difference between title and tag?
getTitle specifies the friendly name associated with the control; getTag is a tag associated with it.
Does the control survive saving?
Yes. The reloaded document returned the same title, tag and type.
API Reference Summary
| Class / Method | Description |
|---|---|
StructuredDocumentTag | Represents a structured document tag (SDT or content control) in a document. |
SdtType | Specifies the type of a structured document tag (SDT) node. |
DocumentBuilder.insertStructuredDocumentTag(type) | Inserts a StructuredDocumentTag into the document. |
Related Guides
- Fields
- Bookmarks
- Working with Text
- How to Add a Content Control to a Word Document in Java (knowledge base)