TemplatePart¶

featherdoc::TemplatePart is the shared editing surface for document body, header, footer, and section-resolved parts. Use it when a workflow needs the same template operation to work outside the main body, especially bookmark filling, content-control replacement, and part-local template validation.

Common Tasks¶

Use this page as a part-local reference:

Fill named bookmarks: call list_bookmarks(), find_bookmark(...), replace_bookmark_text(...), or fill_bookmarks(...).
Fill content controls: use find_content_controls_by_tag(...) and replace_content_control_text_by_tag(...).
Replace a template slot with generated content: use the bookmark or content-control replacement methods for paragraphs, tables, rows, and images.
Edit header/footer content with the same API as the body: get a TemplatePart from Document and then call paragraphs(), tables(), append_paragraph(...), or append_table(...).
Validate a local template surface: use validate_template(...) before writing values.

Success And Failure Semantics¶

Return shape	Success	Failure or no-op
`operator bool()`	`true` means the part points at an available package XML part.	`false` means the body/header/footer part could not be resolved.
`std::size_t`	Non-zero value is the count of matching slots changed or appended.	`0` means no matching bookmark, content control, hyperlink, or image insertion target was found.
`bool`	`true` means the requested XML mutation was applied.	`false` means the target was unavailable, unsupported, or unchanged.
`bookmark_fill_result`	Inspect `matched` and `replaced` for successful fills.	Inspect `missing_bookmarks` before treating the template as complete.
`template_validation_result`	Truthy result means required slots passed validation.	Missing or mismatched slots are listed in the result details.

Short Example¶

auto body = doc.body_template();
if (!body) return 1;

body.replace_bookmark_text("invoice_no", "INV-2026-001");
body.replace_content_control_text_by_tag("status", "approved");

Typed Signature Guide¶

Use TemplatePart for part-local editing. It is valid when operator bool() returns true. Methods returning std::size_t report how many matching bookmarks or content controls were changed. Methods returning bool report whether the requested XML mutation was applied.

Signature	Parameters	Return semantics
`explicit operator bool() const noexcept`	None.	`true` when the part points at an available package XML part.
`std::string_view entry_name() const noexcept`	None.	Package entry name such as `word/document.xml`.
`Paragraph append_paragraph(const std::string &text = {}, formatting_flag formatting = formatting_flag::none)`	`text`: inserted paragraph text. `formatting`: optional first-run formatting.	New paragraph handle in the current part.
`Table append_table(std::size_t row_count = 1U, std::size_t column_count = 1U)`	`row_count` and `column_count`: initial table shape.	New table handle in the current part.
`bookmark_fill_result fill_bookmarks(std::span<const bookmark_text_binding> bindings)`	`bindings`: bookmark-name/text pairs.	Matched, replaced, and missing-bookmark counts.
`std::size_t replace_bookmark_text(const std::string &bookmark_name, const std::string &replacement)`	`bookmark_name`: target bookmark. `replacement`: inserted text.	Number of bookmark instances replaced.
`std::size_t replace_content_control_text_by_tag(std::string_view tag, std::string_view replacement)`	`tag`: content-control tag. `replacement`: inserted text.	Number of matching controls replaced.
`std::size_t replace_content_control_with_table_by_tag(std::string_view tag, const std::vector<std::vector<std::string>> &rows)`	`tag`: target control. `rows`: generated row/cell text matrix.	Number of matching controls replaced with a table.
`template_validation_result validate_template(std::span<const template_slot_requirement> requirements) const`	`requirements`: required bookmark/content-control slots for this part.	Validation result with missing and mismatched slots.
`std::size_t append_hyperlink(std::string_view text, std::string_view target)`	`text`: visible hyperlink text. `target`: URL or relationship target.	Created hyperlink count; `0` means no hyperlink was added.

Part Basics¶

Method	Returns	Purpose
`entry_name() const`	`std::string_view`	Return the package entry name for this part.
`paragraphs()`	`Paragraph`	Iterate paragraph content in the part.
`append_paragraph(text, formatting)`	`Paragraph`	Append a paragraph with optional run formatting.
`tables()`	`Table`	Iterate table content in the part.
`append_table(row_count, column_count)`	`Table`	Append a table with the requested shape.

Bookmarks¶

Method	Returns	Purpose
`list_bookmarks() const`	`std::vector<bookmark_summary>`	Enumerate bookmark slots in this part.
`find_bookmark(bookmark_name) const`	`std::optional<bookmark_summary>`	Find one bookmark by name.
`replace_bookmark_text(bookmark_name, replacement)`	`std::size_t`	Replace bookmark text and return the number of matched slots.
`fill_bookmarks(bindings)`	`bookmark_fill_result`	Fill multiple bookmarks in one call and report misses.
`replace_bookmark_with_paragraphs(bookmark_name, paragraphs)`	`std::size_t`	Replace a bookmark with paragraph content.
`replace_bookmark_with_table(bookmark_name, rows)`	`std::size_t`	Replace a bookmark with a generated table.
`replace_bookmark_with_image(bookmark_name, image_path)`	`std::size_t`	Replace a bookmark with an image run.
`set_bookmark_block_visibility(bookmark_name, visible)`	`std::size_t`	Show or hide the block that contains a bookmark.

Content Controls¶

Method	Returns	Purpose
`list_content_controls() const`	`std::vector<content_control_summary>`	Enumerate structured document tags.
`find_content_controls_by_tag(tag) const`	`std::vector<content_control_summary>`	Find controls by business tag.
`find_content_controls_by_alias(alias) const`	`std::vector<content_control_summary>`	Find controls by visible alias.
`replace_content_control_text_by_tag(tag, replacement)`	`std::size_t`	Replace plain text in matching controls.
`replace_content_control_with_paragraphs_by_tag(tag, paragraphs)`	`std::size_t`	Replace matching controls with paragraph content.
`replace_content_control_with_table_by_tag(tag, rows)`	`std::size_t`	Replace matching controls with a table.
`replace_content_control_with_image_by_tag(tag, image_path)`	`std::size_t`	Replace matching controls with an image.
`set_content_control_form_state_by_tag(tag, options)`	`std::size_t`	Update checkbox, date, dropdown, combo-box, lock, or binding state.

Template Validation¶

Method	Returns	Purpose
`validate_template(requirements) const`	`template_validation_result`	Validate required bookmark and content-control slots.

Document-Level Schema Workflows¶

validate_template_schema(...), scan_template_schema(...), build_template_schema_patch_from_scan(...), and onboard_template(...) are featherdoc::Document APIs because they can aggregate body, header, footer, and section-targeted template slots. Use TemplatePart for part-local slot filling and validate_template(...) checks, then use Document for whole-document schema governance.

Example¶

auto part = doc.body_template();

auto result = part.fill_bookmarks({
    {"invoice_no", "INV-2026-001"},
    {"customer_name", "Ada Lovelace"},
});

part.replace_content_control_text_by_tag("status", "approved");
auto validation = part.validate_template({
    {"invoice_no", featherdoc::template_slot_kind::text, true},
    {"status", featherdoc::template_slot_kind::text, false},
});

if (!result.missing_bookmarks.empty() || !validation) {
    return 1;
}

return doc.save_as("filled.docx") ? 1 : 0;