Skip to content

TemplateRenderer

Jump to bottom
Viames Marino edited this page Mar 26, 2026 · 2 revisions

Pair framework: TemplateRenderer

Pair\Html\TemplateRenderer is the low-level renderer for Pair template files.

It reads an HTML/PHP template, replaces {{placeholder}} tokens, renders widget placeholders, and prints the final HTML.

This class is most relevant when you work on the application shell rather than on a module layout.

Main method

TemplateRenderer::parse(string $styleFile): void

This is the only public method of the class and the main reason it exists.

Current behavior:

  1. reads the template file content
  2. scans available widgets through Widget::availableWidgets()
  3. replaces matching widget placeholders with Widget::render()
  4. replaces built-in placeholders mapped from Application
  5. replaces common placeholders such as baseHref, styles, and scripts
  6. replaces dynamic variables from Application::getVars()
  7. prints the final HTML

Important implementation detail: parse() prints the result directly, it does not return a string.

Built-in placeholders

Mapped from Application properties:

  • {{langCode}} -> Application->langCode
  • {{title}} -> Application->pageTitle
  • {{heading}} -> Application->pageHeading
  • {{content}} -> Application->pageContent
  • {{logBar}} -> Application->logBar

Common placeholders:

  • {{baseHref}}
  • {{styles}}
  • {{scripts}}

Dynamic placeholders:

  • any key stored in Application::var(...)
  • any unknown property assigned through Application::__set(...)

Unknown placeholders are replaced with an empty string.

Widget placeholders

If a widget named footerWidget is available, a placeholder like this:

{{footerWidget}}

is replaced with the widget output.

Current implementation detail: each widget placeholder name is replaced only once per render pass because the internal preg_replace(...) call uses a limit of 1.

Template file example

<!doctype html>
<html lang="{{langCode}}">
<head>
  <!-- Base path for relative assets and links. -->
  <base href="{{baseHref}}">

  <!-- Page title from Application->pageTitle. -->
  <title>{{title}}</title>

  <!-- CSS tags generated by Application::styles(). -->
  {{styles}}
</head>
<body>
  <!-- Main application content generated by the MVC flow. -->
  <main>{{content}}</main>

  <!-- Widget placeholder rendered through Widget::render(). -->
  {{footerWidget}}

  <!-- JS tags generated by Application::scripts(). -->
  {{scripts}}
</body>
</html>

Usage example

use Pair\Core\Application;
use Pair\Html\TemplateRenderer;

$app = Application::getInstance();

// Exposes one custom placeholder available as {{footerNote}}.
$app->var('footerNote', 'Generated at ' . date('c'));

// Parses the template and prints the final HTML.
TemplateRenderer::parse(APPLICATION_PATH . '/templates/default.php');

Practical pattern: feeding custom placeholders

use Pair\Core\Application;

$app = Application::getInstance();

// Assigns multiple template variables in one call.
$app->var([
    'sectionClass' => 'orders-shell',
    'footerNote' => 'Orders dashboard',
]);

Those values become available as {{sectionClass}} and {{footerNote}} inside the template.

Secondary notes worth knowing

Because TemplateRenderer only exposes one public method, most of the useful details are implementation details:

  • widget placeholders are resolved before generic placeholders
  • only scalar values and objects with __toString() are rendered from Application::getVars()
  • built-in placeholders such as {{styles}} and {{scripts}} come from Application, not from template vars

Notes and caveats

  • parse() expects the template file to exist and be readable.
  • Unknown placeholders are removed, not preserved for a second pass.
  • Repeating the same widget placeholder twice in one template currently replaces only the first occurrence.

See also: Widget, Application, View, Template.

Clone this wiki locally