iofficeai--officecli/examples/word/content-controls.md

Content Controls Showcase

Exercises the docx sdt property surface — structured document tags, better known as content controls: bounded regions Word treats as fillable form fields. Three files work together:

• content-controls.py — builds the doc via the officecli Python SDK.
• content-controls.sh — the CLI twin (produces the shipped .docx).
• content-controls.docx — the generated document, a small employee-intake form.
• content-controls.md — this file.

The sdt element

An sdt is added under /body (block-level, wrapping paragraphs) and reads back at the stable path /body/sdt[@sdtId=N] (positional /body/sdt[N] also works):

officecli add file.docx /body --type sdt --prop type=text --prop alias="Full Name"
officecli query file.docx sdt          # list every control with its props
officecli get   file.docx /body/sdt[1] # read one control's property bag

The control type cannot be changed after creation. text/richtext/dropdown/combobox/date/picture/group/checkbox can all be created at add-time. (buildingBlockGallery/repeatingSection still require creating the control in Word first, then editing via the CLI.)

Built on the officecli-sdk (one resident, writes shipped over the pipe); falls back to the in-repo SDK copy when the package isn't pip-installed.

Regenerate

cd examples/word
pip install officecli-sdk
python3 content-controls.py        # or: bash content-controls.sh
# → content-controls.docx

Control types demonstrated

#	Type	Purpose	Type-specific props
1	text (plainText)	Single-line text field	text= initial/placeholder content
2	dropdown	Pick-one, typing disabled	items=, dropDown.lastValue=
3	combobox	Pick-one or free type	items= (display|value), comboBox.lastValue=
4	date	Calendar picker	format=, date.fullDate/calendar/lid/storeMappedDataAs=
5	picture	Image-insert placeholder	—
6	richtext	Formatted multi-run field	text=
7	group	Locked grouping wrapper	—
8	checkbox	Check-box toggle (☒/☐)	checked= (true/false)

Shared props (every control type)

officecli add file.docx /body --type sdt --prop type=text \
  --prop alias="Full Name" \          # human-readable label shown in Word
  --prop tag=fullName \               # machine-readable data-binding key
  --prop text="[Enter full legal name]" \  # initial / placeholder content
  --prop lock=unlocked \              # unlocked | contentLocked | sdtLocked | sdtContentLocked
  --prop placeholderText=DefaultPlaceholder  # docPart gallery reference

lock semantics: contentLocked freezes the content (readback editable=false), sdtLocked blocks deletion of the control, sdtContentLocked does both. placeholder=true marks the control as currently showing its placeholder text (<w:showingPlcHdr/>).

Per-type props

2 + 3. dropDown / comboBox — choice lists

# dropDown: choices only, no free typing
officecli add file.docx /body --type sdt --prop type=dropdown \
  --prop alias="Department" --prop tag=department \
  --prop items="Sales,Engineering,Human Resources,Finance,Operations" \
  --prop dropDown.lastValue=Engineering

# comboBox: same, but the user may also type a value not in the list.
# items= supports display|value form when the stored value differs from the label.
officecli add file.docx /body --type sdt --prop type=combobox \
  --prop alias="Office Location" --prop tag=office \
  --prop items="New York|NYC,London|LON,Singapore|SIN,Remote|REMOTE" \
  --prop comboBox.lastValue=LON

items= is a comma list; each entry is either display or display|value. {dropDown,comboBox}.lastValue= is the currently-selected stored value.

4. date — calendar picker

officecli add file.docx /body --type sdt --prop type=date \
  --prop alias="Start Date" --prop tag=startDate \
  --prop format="yyyy-MM-dd" \
  --prop date.fullDate=2026-02-01T00:00:00Z \
  --prop date.calendar=gregorian --prop date.lid=en-US \
  --prop date.storeMappedDataAs=dateTime

format= is the display mask; date.fullDate is the actual selected value (ISO-8601 UTC), distinct from the mask. date.calendar (e.g. gregorian, hijri, japan), date.lid (locale id), and date.storeMappedDataAs (dateTime/date/text) round out the picker.

5. picture — image placeholder

officecli add file.docx /body --type sdt --prop type=picture \
  --prop alias="Profile Photo" --prop tag=photo

6. richText — formatted field

officecli add file.docx /body --type sdt --prop type=richtext \
  --prop alias="Reviewer Notes" --prop tag=notes \
  --prop text="Manager may add formatted commentary here." \
  --prop lock=contentLocked

7. group — locked wrapper

officecli add file.docx /body --type sdt --prop type=group \
  --prop alias="Approval Block" --prop tag=approval \
  --prop text="Approved by HR — signature on file." \
  --prop lock=sdtContentLocked

8. checkbox — check-box toggle

A real Word check-box content control. checked=true renders ☒ (2612), checked=false renders ☐ (2610); the state is stored as a <w14:checkbox> marker in the control's sdtPr. get reads type=checkbox and checked.

officecli add file.docx /body --type sdt --prop type=checkbox \
  --prop alias="Approved" --prop tag=hrApproved \
  --prop checked=true

Modifying after creation (set)

alias, tag, lock, and text are settable. The per-type props (dropDown.lastValue, comboBox.lastValue, items, format, date.*, placeholderText) are add/get-only — set at creation, read back on get, but not modifiable via set.

officecli set file.docx /body/sdt[2] --prop alias="Home Department" --prop lock=sdtLocked

Inspect

officecli query content-controls.docx sdt      # one line per control
officecli get   content-controls.docx /body/sdt[1]

/body/sdt[@sdtId=1] (sdt) "[Enter full legal name]" alias=Full Name tag=fullName lock=unlocked type=text editable=true placeholderText=DefaultPlaceholder
/body/sdt[@sdtId=2] (sdt) "" alias=Home Department tag=department lock=sdtLocked type=dropdown items=Sales,Engineering,Human Resources,Finance,Operations dropDown.lastValue=Engineering
/body/sdt[@sdtId=4] (sdt) "" alias=Start Date tag=startDate type=date format=yyyy-MM-dd date.fullDate=2026-02-01T00:00:00Z date.calendar=gregorian date.lid=en-US date.storeMappedDataAs=dateTime
/body/sdt[@sdtId=6] (sdt) "Manager may add formatted commentary here." alias=Reviewer Notes tag=notes lock=contentLocked type=richtext editable=false

Read-only readback keys: id (source of @sdtId) and editable (mirrors lock). Full list: officecli help docx sdt.