Binding basics

This section covers the main public API of DomTemplate.

Here we will look at the three most common operations:

• bind one value everywhere it's needed
• bind a single named key/value pair
• bind a whole map or object in one operation

Along the way we'll also look at bind contexts, selector strings, and placeholders.

The data-bind:* pattern

At the HTML level, the basic idea is always the same:

<span data-bind:text="name">Guest</span>
<a data-bind:href="#">View profile</a>

The bit after data-bind: is the bind property (e.g. the property of the HTML Element that we'll be setting), and the attribute's value is known as the bind key (e.g. the key of the data structure we'll use for the value).

When we bind the key name, the first element changes. When we bind the key profileUrl, the second element changes - only elements with a matching bind key will be affected, allowing you to keep default values stored within the HTML page itself.

bindValue

bindValue($value, $context = null) binds one value to every matching data-bind:* attribute that has no key.

HTML:

<p data-bind:text>Hello</p>
<p data-bind:text>Goodbye</p>

PHP:

$binder->bindValue("Welcome");

Output HTML:

<p>Welcome</p>
<p>Welcome</p>

This is especially useful for simple repeated text, scalar list items, or placeholders without named keys.

bindKeyValue

bindKeyValue(string $key, $value, $context = null) binds one named key/value pair.

HTML:

<h1>Hello, <span data-bind:text="name">you</span>!</h1>
<p>Signed in as <strong data-bind:text="name">guest</strong>.</p>

PHP:

$binder->bindKeyValue("name", "Cody");

Output HTML:

<h1>Hello, <span>Cody</span>!</h1>
<p>Signed in as <strong>Cody</strong>.</p>

bindData

bindData($data, $context = null) binds a whole key/value data source in one call.

HTML:

<h1 data-bind:text="username">Guest</h1>
<p>Email: <span data-bind:text="email">guest@example.com</span></p>
<p>Status: <span data-bind:text="status">Offline</span></p>

PHP:

$binder->bindData([
	"username" => "Ada",
	"email" => "ada@example.com",
	"status" => "Reviewing pull requests",
]);

If we do this, DomTemplate iterates over each key and applies it anywhere that key is used within the current scope.

Bind contexts

All the main binding methods accept an optional context.

Pass an element

$profileSection = $document->querySelector("#profile");
$binder->bindData($profileData, $profileSection);

This keeps the binding local to one part of the page.

Pass a selector string

$binder->bindData($profileData, "#profile");

This is often a little more convenient when we already know the selector we want.

Note

If no element matches the selector string, DomTemplate throws ContextElementNotFoundException.

Placeholders with {{curly braces}}

Sometimes we do not want to replace the whole text node or the whole attribute value. We only want to inject part of it.

HTML:

<a href="/user/{{id}}">View {{name ?? this user}}</a>

PHP:

$binder->bindData([
	"id" => 42,
	"name" => "Cody",
]);

Output HTML:

<a href="/user/42">View Cody</a>

If name is null or an empty string, the default text this user is used instead.

bindValue vs placeholders

As a rule of thumb:

• use data-bind:text, data-bind:href, and friends when we want to replace a whole property
• use {{placeholder}} when we only want to replace part of a string

That keeps the HTML easy to read and makes the default state obvious to anyone scanning the template.

When to clean the document

After binding is finished, call:

$binder->cleanupDocument();

That strips DomTemplate's helper attributes from the output and removes any unbound data-element nodes.

---

We now have the core mental model in place. Next, move on to bind properties and modifiers so we can see the different ways an element can be mutated.