Templating

The template engine processes ${variable} placeholders and foreach loops inside the document tree, enabling data-driven document generation.

DocraftTemplateEngine

class DocraftTemplateEngine

The DocraftTemplateEngine class stores template variables/image data and resolves ${...} expressions against them.

Used by both pipelines: legacy walks the whole document tree calling render_template_string() itself before layout/render, while docraft::loom::craft::DocraftLoomTreeBuilder calls it per string as it builds each node (Text/Title/Subtitle content, Image src, <Foreach>’s own model attribute), passing the current Foreach iteration’s item where one is in scope.

Public Functions

DocraftTemplateEngine() = default

void add_template_variable(const std::string &name, const std::string &value)

Adds a template variable.

Parameters:

name – Variable name (case-insensitive).
value – Variable value inserted into templates.

std::string find_template_variable(const std::string &name) const

Retrieves a template variable value.

Parameters:: name – Variable name (case-insensitive).
Throws:: docraft::exception::DocraftException – if not found.
Returns:: Stored value.

void clear_template_variables(): Clears all template variables.

void remove_template_variable(const std::string &name)

Removes a template variable by name.

Parameters:: name – Variable name (case-insensitive).
Throws:: docraft::exception::DocraftException – if not found.

int items() const: Returns the number of stored template variables.

bool has_template_variable(const std::string &name) const

Checks if a template variable exists.

Parameters:: name – Variable name (case-insensitive).

void add_template_variables_from_json(const nlohmann::json &json)

Registers every field of a JSON object as a template variable, flattening nested objects into dot-notation keys — e.g.

{"user":{"name":"Bob"}} registers "user.name" -> "Bob", so ${user.name} resolves — rather than registering the nested object as a single JSON-text variable. Strings are registered as-is; every other leaf value (numbers/bools/null/arrays) is registered as its compact JSON text — e.g. an array field becomes a JSON array string usable directly as a <Foreach model="${field}"> attribute.

Parameters:

json – JSON object whose fields to register.

Throws:

docraft::exception::DataFormatException – if json is not a JSON object.
docraft::exception::TemplateVariableExistsException – if a flattened key collides with one already registered.

void add_image_data(const std::string &image_id, const std::vector<unsigned char> &data, int width, int height)

Adds raw RGB image data.

Parameters:

image_id – Image id used by <Image data=”…”> in templates (case-insensitive).
data – Raw RGB bytes (3 bytes per pixel, row-major).
width – Pixel width.
height – Pixel height.

void add_base64_image_data(const std::string &image_id, std::string_view base64, int width, int height)

Adds raw RGB image data from a base64 string.

Parameters:

image_id – Image id used by <Image data=”…”> in templates (case-insensitive).
base64 – Base64 string with raw RGB bytes (no data URI prefix).
width – Pixel width.
height – Pixel height.

Throws:

docraft::exception::DataFormatException – if decoded size does not match width*height*3.

const RawImageData &get_image_data(const std::string &image_id) const

Retrieves raw image data by id.

Parameters:: image_id – Image id (case-insensitive).
Throws:: docraft::exception::DocraftException – if not found.
Returns:: RawImageData reference.

std::string render_template_string(const std::string &text) const

Renders a template string, replacing every ${variable} with its registered value.

Has no notion of a Foreach iteration item — callers that may or may not have one in scope (e.g. docraft::loom::craft::DocraftLoomTreeBuilder) decide which of this or render_template_string_foreach_item() to call. An unknown variable is left in the output exactly as written.

Parameters:: text – Template string to render.
Returns:: Rendered string with every resolvable ${variable} replaced.

std::string render_template_string_foreach_item(const std::string &text, const nlohmann::json &item) const

Renders a template string against one Foreach iteration’s item, replacing every ${data("field")} with that field of item and every ${variable} with its registered value (data(...) is tried first).

Note

data("field_name") reads a top-level field only; item cannot be nested more than one level.

Parameters:

text – Template string to render.
item – JSON object supplying the current Foreach iteration’s fields.

Returns:

Rendered string with every resolvable expression replaced.

struct RawImageData

Struct to hold raw image data along with its dimensions.

Public Members

std::vector<unsigned char> data

int width = 0

int height = 0