Structured Document Tags (SDTs) are Word’s content control mechanism. SDTs define regions in a document where content is constrained or structured — rich text controls, date pickers, dropdown lists, and more.
1. SDT Structure
An SDT consists of two parts:
- Properties (
w:sdtPr) -
Define the content control type, appearance, placeholder text, data binding, and constraints.
- Content (
w:sdtContent) -
The actual document content inside the control, using standard WordProcessingML elements.
# Access SDT properties and content
sdt = paragraph.sdt
sdt.properties.alias # => "Title"
sdt.properties.tag # => "doc_title"
sdt.properties.locked? # => true
sdt.content.paragraphs # => array of paragraphs inside the SDT2. Content Control Types
SDTs support several content control types, identified by their child element in sdtPr:
- Rich text (
w:richText) -
Free-form rich text content. The default type.
- Plain text (
w:text) -
Plain text input, optionally with length limits.
- Date (
w:date) -
Date picker with format string and calendar type.
- Dropdown (
w:comboBox) -
Combo box with predefined entries.
- List (
w:dropDownList) -
Dropdown list with restricted choices.
- Picture (
w:picture) -
Image insertion control.
- Checkbox (
w:checkbox) -
Boolean checkbox control.
- Repeating section (
w:repeatingSection) -
Repeatable block of content.
3. Data Binding
SDTs can be bound to custom XML data through XML mapping:
# SDT with data binding to custom XML part
sdt.properties.data_binding do |binding|
binding.xpath = "/invoice/number"
binding.store_item_id = "{12345678-1234-1234-1234-123456789012}"
endWhen a data binding is configured, the SDT content is synchronized with the corresponding XML node in a custom XML part.
4. SDT Appearance
SDTs can be displayed in several visual modes:
- BoundingBox
-
Shows a visible box around the content control.
- Tags
-
Shows start and end markers.
- Hidden
-
No visual indicators.
- Default
-
Uses Word’s default display settings.