Skip to content

sdt

sdt

The ContentControl proxy object for a structured document tag (w:sdt).

ContentControl 

ContentControl(sdt: CT_Sdt, parent: ProvidesStoryPart)

Bases: Parented

Proxy for a w:sdt element, a structured document tag or "content control".

Content controls are what Word uses for form fields in modern documents, for template placeholders, and for regions bound to a data source. Their content appears in .paragraphs, .iter_inner_content() and the rest of the read API as though the wrapper were not there; this object is how the wrapper itself is inspected.

Source code in src/docx/sdt.py 
29
30
31
def __init__(self, sdt: CT_Sdt, parent: t.ProvidesStoryPart):
    super(ContentControl, self).__init__(parent)
    self._element = self._sdt = sdt

alias property 

alias: str | None

The friendly name Word shows on this control, or None if not set.

id property 

id: int | None

The numeric id of this control, or None if not set.

is_block_level property 

is_block_level: bool

True when this control wraps block-level content.

A block-level control contains paragraphs or tables; a run-level control sits inside a paragraph and contains runs.

paragraphs property 

paragraphs: List[Paragraph]

The paragraphs directly inside this control, in document order.

runs property 

runs: List[Run]

The runs directly inside this control, for a run-level control.

Empty for a block-level control; the runs of such a control are reached through its paragraphs.

showing_placeholder property 

showing_placeholder: bool

True when this control is currently displaying its placeholder text.

The text of such a control is the prompt shown to the user, not a value they entered, which is worth distinguishing when harvesting values from a form.

tables property 

tables: List[Table]

The tables directly inside this control, in document order.

tag property 

tag: str | None

The programmatic identifier of this control, or None if not set.

Unlike .alias, the tag is not shown to the user; it is what code binding to a template matches on.

text property 

text: str

All the text inside this control.

Paragraphs are separated by newlines, as for a table cell.

type property 

type: WD_CONTENT_CONTROL_TYPE | None

Member of WdContentControlType, or None when the control names no kind.

Word treats a control with no declared kind as rich text, but that is a default rather than a statement, so it is reported as None here.

iter_inner_content 

iter_inner_content() -> Iterator[Paragraph | Table]

Generate each Paragraph or Table in this control, in document order.

Yields nothing for a run-level control; use .runs for one.

Source code in src/docx/sdt.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
def iter_inner_content(self) -> Iterator[Paragraph | Table]:
    """Generate each |Paragraph| or |Table| in this control, in document order.

    Yields nothing for a run-level control; use `.runs` for one.
    """
    from docx.table import Table
    from docx.text.paragraph import Paragraph

    sdtContent = self._sdt.sdtContent
    if sdtContent is None:
        return
    for element in iter_block_content(sdtContent):
        yield (Paragraph(element, self) if isinstance(element, CT_P) else Table(element, self))