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

RequirementDetail
Java8 or later
DependencyThe package from Installation
Importimport com.aspose.words.*;
CodeThe 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: false

Tips 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).
  • SdtType has other types, for example DROP_DOWN_LIST, DATE and CHECKBOX; this page ran only PLAIN_TEXT.

Common Issues

IssueCauseFix
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 / MethodDescription
StructuredDocumentTagRepresents a structured document tag (SDT or content control) in a document.
SdtTypeSpecifies the type of a structured document tag (SDT) node.
DocumentBuilder.insertStructuredDocumentTag(type)Inserts a StructuredDocumentTag into the document.

Related Guides

See Also