Understanding Document Structure

This section provides an overview of how documents are conceptually structured and composed within our system. We follow a layered approach that promotes reusability, modularity, and clarity.

Elements

At the foundation of every document are Elements. These are the most basic, atomic parts used to render content on a page.

Elements are primitive components that directly represent visual or textual content in a document.

Text – Static or dynamic textual content
Image – Embedded images or icons
Table – Display tabular data
Columns – Display content in multiple columns

Blocks

Blocks are reusable groupings of Elements and/or other Blocks.
They allow developers to encapsulate common patterns, making document creation more efficient and maintainable.

Key Characteristics

Blocks can be nested (a Block can contain other Blocks).
Designed to be reused across different documents or templates.
Can include logic or parameters to dynamically adjust content (if supported by the generator engine).

Example Use Cases

A Header Block that contains a logo and page title.
A Table Row Block that includes text and layout elements for rows in a data table.
A Contact Info Block that groups name, email, and phone number.

Regions

Regions are absolutely positioned containers within a Template.
They allow placing content (Blocks or Elements) at fixed positions on the page, outside the normal document flow.

Purpose

Ideal for content that must appear at specific positions, regardless of surrounding content.
Bypass normal flow-based layout and page breaking.
Used when precise placement is required.

Example Use Case

Address Field in a Letter Template: A fixed-position region in the top-left corner of the first page for recipient details.
Watermarks or Page Numbers: Fixed elements rendered at the same position on every page.

Characteristics

Regions live inside Templates.
They can contain Blocks and/or Elements.
Unlike normal content, Regions do not cause page breaks or reflow.
They exist alongside the flowing document content and remain fixed.

Templates

Templates are high-level structures that represent a complete document layout.
They are composed of Blocks and/or Elements arranged in a specific way to form the final output.

Purpose

Serve as the blueprint for generating full documents.
Can be customized or parameterized for dynamic content insertion.
Abstract away repetitive layout logic into a single definition.

Templates bring everything together: they use predefined Blocks and Elements to define how the entire document should look and behave.