Templates¶
A template is a full HTML page or a fragment. PHP finds the nodes marked with a var attribute and changes them.
Loading and rendering¶
use Tk\DomTemplate\Template;
$t = Template::load('<h1 var="title">Default</h1>'); // from a string
$t = Template::file(__DIR__ . '/page.html'); // from a file (the path appears in error messages)
echo $t->render(); // or (string)$t
- Markup starting with
<!doctypeor<html>is a full page; anything else is a fragment. - Fragments may have several top-level nodes, including table rows (
<tr>…</tr><tr>…</tr>) or<option>lists. render()builds the template once. After that it is locked: any change throws aLogicException. Callingrender()again returns the same string.
Marking nodes¶
One attribute, var, names a node. Its suffix sets the kind:
| Markup | Kind | Meaning |
|---|---|---|
var="title" |
var | A node PHP changes. Visible by default. |
var="admin?" |
optional | Removed at render unless PHP shows it. Its content can still be set. |
var="users[]" |
repeat | A sample row, cloned once per item. See Repeats. |
- PHP always uses the bare name:
title,admin,users. - Several nodes may share a name; a call changes all of them.
- Names may contain letters, digits,
-,_and.. - The
varattribute is removed from the output. HTML's ownhiddenattribute is left alone.
Handles and shortcuts¶
$t->var('name') returns a handle on every node with that name. Its methods chain:
$t->var('link')
->text('Docs')
->attr(['href' => '/docs', 'target' => '_blank'])
->addClass('active');
For a single change, use the shortcut on the template:
| Handle | Shortcut | Does |
|---|---|---|
text($s) |
$t->text('x', $s) |
set the text, escaped |
html($h) |
$t->html('x', $h) |
replace the contents with HTML or a template |
append($h) / prepend($h) |
$t->append('x', $h) |
add HTML or a template at the end / start |
replace($h) |
$t->replace('x', $h) |
replace the node itself |
attr($name, $value) / attr([...]) |
$t->attr('x', 'href', $u) |
set attributes |
removeAttr($name) |
remove an attribute | |
addClass($c) / removeClass($c) |
$t->addClass('x', 'active') |
add or remove whole class names |
show($bool) / hide() |
$t->show('x', $cond) / $t->hide('x') |
keep or remove at render |
getText(), getAttr($name), count() |
read |
text()is the only escaped path. Everything else inserts HTML. On a JavaScript or JSON<script>(no type, a JS or JSON type,module,importmap) or a<style>,text()escapes the sequences that could end the element, so JSON in<script type="application/json">is safe. On other script types (text/x-template…) the text is written as is, and text containing<!--or</scriptis refused; on<iframe>,<xmp>,<noembed>,<noframes>and<plaintext>it is refused.- HTML is parsed in the context of the target node, so
html('tbody', '<tr>…</tr>')keeps the rows. attr()values:true, or no value (attr('disabled')), sets an empty attribute (disabled="");falseornullremoves it. Alpine names such as@clickand:classwork.removeClass('btn')removes only thebtnclass, notbtn-primary.$t->has('x')checks whether a name exists, for optional markup in components.- After
replace('x', …), the name refers to the replacement, soshow(),hide()and attribute changes still apply.
Visibility¶
$t->show('edit', $user->canEdit()); // optional: removed unless shown
$t->hide('price'); // plain: removed when hidden
Hidden nodes are removed from the output, not hidden with CSS. Optional nodes are mostly permission checks, so their content never reaches the browser.
Filling an optional node doesn't show it: text('msg', 'Saved') on var="msg?" renders nothing until show('msg') is called too.
Errors¶
| Mistake | Result |
|---|---|
| Unknown name | No var `titel` in page.html. Did you mean `title`? |
A name inside content replaced by html() or replace() |
"`msg` in page.html was inside content that has been replaced" |
Wrong kind (var() on a repeat) |
"`users` is a repeat in page.html, use repeat()" |
| A name used as two kinds, or malformed | Reported when the template loads |
| A change after render | LogicException, always |
Messages name the template by the path given to Template::file(), (string) for load(), or file#name for a Builder component. A suggestion is offered for names of 3 or more characters: within 1 edit up to 4 characters, within 2 edits for longer names.
By default these throw a TemplateException. An Engine with strict: false logs them instead and carries on, which suits production.
HTML5 output¶
Templates are parsed and written by PHP's HTML5 parser, Dom\HTMLDocument, so a few things come out normalised:
- A bare attribute is written with an empty value:
hiddenbecomeshidden="". - Single-quoted attribute values are written with double quotes, escaping as needed.
- Attribute names are lowercased.
- Broken HTML never throws; it is repaired the way browsers repair it.
- Named entities such as
©are written as the character itself; only&,<,>,"and stay as entities. - Templates are read and written as UTF-8, so serve pages as UTF-8. A
<meta charset>naming another charset is reported as a mistake (and rewritten to UTF-8 when lenient). Invalid UTF-8 in template source or in values passed totext(),attr()and the asset methods becomes�(U+FFFD).
DomTemplate reserves the data-tk-key attribute for its own use. <tk-slot> elements written in your HTML are kept.