How to Add a Content Control to a Word Document in Java

How to Add a Content Control to a Word Document in Java

Aspose.Words FOSS for Java inserts content controls, also called structured document tags, with DocumentBuilder.insertStructuredDocumentTag. This guide inserts a plain text control with a title and a tag and reads it back, with the library from Maven Central.

Step-by-Step Guide

Step 1: Install the Package

Add the package to your build. The library needs Java 8 or later.

<dependency>
  <groupId>org.aspose</groupId>
  <artifactId>aspose-words-foss</artifactId>
  <version>26.3.0</version>
</dependency>

Step 2: Import the Classes

All classes are in the com.aspose.words package, so the example starts with import com.aspose.words.*;.


Step 3: Insert the Control

insertStructuredDocumentTag(SdtType.PLAIN_TEXT) inserts the control at the cursor and returns it.


Step 4: Set Title, Tag and Text

setTitle and setTag name the control. removeAllChildren clears the placeholder content, appendChild(new Run(doc, text)) adds the text and isShowingPlaceholderText(false) marks it as real text. The example writes Name: first, so that the control is inline.

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: false

Step 5: Read It Back

After saving and reloading the example found 1 control with the title Customer name, the tag customer-name, the type plain text, the text Acme Corp and no placeholder flag.

Common Issues and Fixes

The control shows placeholder text. Remove the children before you append your text and call isShowingPlaceholderText(false); the flag stays set otherwise.

appendChild throws an IllegalArgumentException. The control is block level, for example when it is the first thing in an empty document. Write some text with the builder first so that it is inline.

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.

Frequently Asked Questions

How do I find a control by its tag?

Loop over getChildNodes(NodeType.STRUCTURED_DOCUMENT_TAG, true) and compare getTag.

Which types exist?

SdtType lists them, for example PLAIN_TEXT, RICH_TEXT, DROP_DOWN_LIST, DATE and CHECKBOX.

See Also