Working with Structured Document Tags (Content Controls)

Working with Structured Document Tags (Content Controls)

A structured document tag (SDT), known in the Word UI as a content control, wraps a piece of document content with typed, constrained editing behavior – a checkbox, a date picker, a drop-down list, or a plain- or rich-text placeholder. Aspose.Words FOSS for .NET models these through the Aspose.Words.Markup namespace, headlined by the StructuredDocumentTag class. This page covers inserting content controls, configuring each type, finding and removing them, and binding them to custom XML data.

The Structured Document Tag Object Model

StructuredDocumentTag is a CompositeNode that also implements IMarkupNode, ITrackableNode, and IStructuredDocumentTag. SdtType identifies which kind of control it is. Tag and Title hold the identifying strings authors set in Word; Placeholder (a BuildingBlock) and PlaceholderName supply the prompt text shown when the control is empty, reported via IsShowingPlaceholderText. LockContentControl prevents the control from being deleted, and LockContents prevents its contents from being edited, independent of each other.

Inserting Content Controls

DocumentBuilder.InsertStructuredDocumentTag(SdtType) inserts a new control at the cursor, but only for seven of the SdtType values: PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, and Date. RepeatingSection and RepeatingSectionItem cannot be inserted at a text cursor this way – they wrap entire paragraphs or table rows instead. The remaining SdtType values that appear in Word files but are not present in the Word UI as insertable types – None, Bibliography, Citation, Equation, BuildingBlockGallery, DocPartObj, Group, and EntityPicker – are not supported by this insertion method.

Type-Specific Content

A checkbox control’s state is StructuredDocumentTag.Checked; SetCheckedSymbol() and SetUncheckedSymbol() set the glyphs shown for each state. A date control stores its value in FullDate, with DateDisplayFormat and DateDisplayLocale controlling how it is rendered, DateStorageFormat (an SdtDateStorageFormat) controlling how it is stored when bound to XML data, and CalendarType (an SdtCalendarType) selecting the calendar system. A drop-down list or combo box exposes its choices through ListItems, an SdtListItemCollection of SdtListItem (DisplayText, Value) with a SelectedValue. A plain-text control’s Multiline property allows or disallows line breaks inside it.

Appearance and Locking

Appearance (SdtAppearance) controls how the control is visually delimited in Word. Color sets its highlight color, and ContentsFont / EndCharacterFont control the font applied to its contents and its trailing end character. LockContentControl and LockContents are independent switches – the first blocks deletion of the control itself, the second blocks editing of what is inside it.

Finding and Removing Content Controls

Range.StructuredDocumentTags returns a StructuredDocumentTagCollection scoped to that range, with GetById(), GetByTag(), and GetByTitle() for targeted lookup alongside Remove() and RemoveAt(). On an individual StructuredDocumentTag, Remove() deletes the control and its contents together, RemoveSelfOnly() deletes only the wrapper and keeps its contents in the document, and Clear() empties the control’s contents while keeping the control itself.

XML Data Binding

StructuredDocumentTag.XmlMapping is an XmlMapping instance describing a binding to a custom XML part in the document: CustomXmlPart, XPath, PrefixMappings, StoreItemId, and IsMapped. SetMapping() establishes the binding to an existing custom XML part and Delete() removes it.

Multi-Section (Ranged) Content Controls

A content control that spans more than one section – reported by IsMultiSection – is represented not by a single StructuredDocumentTag node but by a pair of StructuredDocumentTagRangeStart and StructuredDocumentTagRangeEnd nodes, connected through StructuredDocumentTagRangeStart.RangeEnd. Both the single-node and ranged forms implement the common IStructuredDocumentTag interface, so code that only needs Tag, Title, SdtType, Placeholder, and similar identifying properties can work with either form uniformly.

Tips and Best Practices

• Check DocumentBuilder.InsertStructuredDocumentTag()’s supported-type list before relying on it – only PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, and Date can be inserted at the cursor; other types throw an exception.
• Use RemoveSelfOnly() instead of Remove() when you want to “flatten” a content control – keep its contents in the document but drop the control wrapper.
• Populate ListItems before you expect a DropDownList or ComboBox control to show choices, and set SelectedValue to pick the active one.
• Program against IStructuredDocumentTag rather than StructuredDocumentTag directly if your code needs to handle both ordinary and multi-section (ranged) content controls the same way.
• XmlMapping.SetMapping() binds to a custom XML part that must already exist in the document’s custom XML data store – add or load the XML data before mapping a control to it.

Common Issues

FAQ

Which content control types can I insert directly with DocumentBuilder?

PlainText, RichText, Checkbox, DropDownList, ComboBox, Picture, and Date. Other SdtType values are not supported by InsertStructuredDocumentTag().

How do I find all content controls with a specific tag?

Use Range.StructuredDocumentTags.GetByTag(), or GetByTitle() / GetById() if you’re matching on those instead.

How do I remove a content control but keep its content?

Call StructuredDocumentTag.RemoveSelfOnly() rather than Remove().

How do I bind a content control to custom XML data?

Call XmlMapping.SetMapping() on the control, pointing it at an existing custom XML part and an XPath expression within it.

What’s the difference between a plain StructuredDocumentTag and a ranged one?

A content control that spans more than one document section is represented as a StructuredDocumentTagRangeStart / StructuredDocumentTagRangeEnd pair instead of a single node; both forms implement IStructuredDocumentTag.

API Reference Summary

See Also

• Aspose.Words — Enterprise Documentation