API reference / Common / Engine types / ContentControl

Interface: ContentControl

A content control's own properties (w:sdtPr + w:sdtEndPr) — what the control is, minus what it wraps.

Level-independent, because the schema's are: CT_SdtBlock, CT_SdtRun, CT_SdtCell and CT_SdtRow differ only in the content they admit, and each carries this same pair. So the level is said by the node that holds this — TextControlBlock or TextControlSpan — and never restated here, where the two could disagree.

Three fields in the whole construct hold a value: a list's last_value, a date's full_date, and a checkbox's checked. Everything else a control "contains" is its content, in the story — those three are the machine-readable twins of what the content displays. The inversion against a field is deliberate and is what the file does: a field's instruction is authoritative and its result the echo, a control's content is authoritative and these the echo.

See Text Model.

Properties

Property	Description
id string	Stable model id — what the co-editing payload map is keyed by.
kind ContentControlKind	The type element, or RichText where the schema's choice is absent.
alias? string	w:alias — the friendly title, shown on the control's tab.
tag? string	w:tag — the machine name. Not an identifier: solution code finds controls by it, and several controls in one document commonly share one.
lock? ContentControlLock	w:lock — what may be edited, and what may be deleted.
placeholder? string	w:placeholder/w:docPart — the name of a glossary document part holding the prompt text, not the text itself. The one field here that reaches outside the story: resolving it is a package lookup, so a control showing "Click here to enter text" holds none of that string.
showingPlaceholder? boolean	w:showingPlcHdr — the content currently shown is that prompt, so the control holds no value yet.
temporary? boolean	w:temporary — remove the control, keeping its content, once it is edited. A one-shot prompt rather than a lasting structure.
binding? ContentControlBinding	w:dataBinding — the custom-XML node this control mirrors. Boxed because most controls are not bound, and this rides in every one.
label? number	w:label.
tabIndex? number	w:tabIndex — where the control sits in the form's tab order.
properties? TextCharacterProperties	w:sdtPr/w:rPr — the opening boundary's character properties. Two homes, as a complex field's marks have: the content between the boundaries carries its own and is authoritative for what the reader sees. See Text Fields.
endProperties? TextCharacterProperties	w:sdtEndPr/w:rPr — the closing boundary's. The schema spells CT_SdtEndPr as an unbounded choice over one optional rPr, which is an accident of authoring: there is one closing boundary, so there is one set of properties for it. Import keeps the first.
appearance? ContentControlAppearance	w15:appearance — how the control's chrome draws.
color? PaintColor	w15:color — the chrome's colour.