Structured Content¶

Structured Content is the PHP-owned document model of the ODT Template Engine.

Use it when a template provides an insertion point such as {{content}}, but PHP should construct the paragraphs, lists, tables, images, or frames that replace that placeholder.

The ownership rule is:

Writer owns the surrounding document and insertion point; PHP owns the structure inserted at that point.

If the structure already exists in the Writer template and should remain Writer-owned, use the Writer-native object APIs instead.

setElement()¶

Recommended · Structured Content

Inserts a PHP-built OdtElement at a template placeholder.

public function setElement(
    string $placeholder,
    OdtElement $element
): void

Parameters¶

Return value¶

void. The method is not fluent.

Lifecycle and side effects¶

setElement() materializes the element into the current working document immediately. It is not staged for the classic render() pass.

During structured insertion the engine also prepares the styles and physical resources required by the element tree. A classic render() is only needed when the same document also contains staged classic values or repeating data.

use OdtTemplateEngine\Elements\RichText;
use OdtTemplateEngine\OdtTemplate;

$template = new OdtTemplate('templates/report.odt');

$content = (new RichText())
    ->addParagraph('Generated by PHP.');

$template->setElement('content', $content);
$template->save('report.odt');

Do not use setElement() when¶

• the value is a simple scalar for the visible template language; use assign();
• the structure already exists as a named Writer object and PHP should only populate or replace its content; use the corresponding Writer-native target API.

Passing an OdtElement through assign() and render() remains a compatibility path, not the recommended structured-content lifecycle.

OdtElement¶

Recommended as the common structured-content type · Advanced for custom element implementations

OdtElement is the abstract base type accepted by setElement() and used to compose structured content.

Application code normally constructs concrete elements such as RichText, Paragraph, RichTable, ImageElement, or DrawTextBox; it does not instantiate OdtElement itself.

The public class also contains materialization, resource-discovery, and style-requirement hooks used by the engine. Those hooks are extension/infrastructure surface and are not part of the normal application authoring API.

Composition¶

Concrete elements own their nested PHP-built structure. For example, a RichText can contain paragraphs, tables, lists, and other elements, while a Paragraph can embed an image or another inline-capable element.

use OdtTemplateEngine\Elements\Paragraph;
use OdtTemplateEngine\Elements\RichText;

$intro = (new Paragraph())
    ->addText('Status: ', ['bold' => true])
    ->addText('ready');

$content = (new RichText())
    ->addParagraph($intro)
    ->addParagraph('Generated detail follows.');

See also¶

• RichText
• Paragraphs & Inline Content
• Template & Document Lifecycle