Modifier characters - phpgt/DomTemplate GitHub Wiki

Bind key modifier characters are special characters that you can add to an element's bind key to add special behaviour.

An example of what this may look like is <button name="do" value="delete" data-bind:disabled="?!isActive">Delete</button>, and <img src="/photo.jpg" data-bind:class=":size" />.

Adding a colon as the first character of the bind key will have the effect of toggling a token's presence, such as in the element's classList.

The "token" in this case is represented by a DOMTokenList object in the underlying DOM implementation, and represents a set of space-separated tokens. Such a set is returned by Element.classList or HTMLLinkElement.relList, and many others. See DOMTokenList on MDN for more information.

It's very common in web user interfaces to want to add or remove a string token to the class attribute. Using the DOM, this can be achieved by doing $element->classList->add("selected");, for example.

HTML:

<img src="/cat.jpg" alt="My cat" data-bind:class=":imageCategory" />

This image element will add a token to the class attribute according to the value of imageCategory.

PHP:

function example(DocumentBinder $binder):void {
	$binder->bindKeyValue("imageCategory", "cat-photo");
}

Output HTML:

<img src="/cat.jpg" alt="My cat" class="cat-photo" />

The name of the class you wish to toggle can be added to the HTML, using a space to separate it from the bind key.

HTML:

<img class="sidebar" src="/cat.jpg" alt="My cat" data-bind:class=":deletedAt deleted" />

This image element will add the deleted token to the class attribute if the deletedAt bind key is not falsey.

PHP:

function example(DocumentBinder $binder, DateTime|null $dateOfDeletion):void {
	$binder->bindKeyValue("deletedAt", $dateOfDeletion);
}

Output HTML:

<img class="sidebar deleted" src="/cat.jpg" alt="My cat" />

or if the $dateOfDeletion variable is null:

<img class="sidebar" src="/cat.jpg" alt="My cat" />

The at character can be added as the first character of the bind key to indicate that the bind key should reference another attribute's value. This feature exists to remove repetition in the HTML - if an element has a name attribute with the value of country, and the bind key should also be country, the name attribute can be referenced using the attribute modifier. This means that if the name attribute's value ever changes, so will the bind key.

HTML:

<input name="country" data-bind:value="@name" />

<!-- which is synonymous to: <input name="country" data-bind:value="country" /> -->

PHP:

function example(DocumentBinder $binder):void {
	$binder->bindKeyValue("country", "TW");
}

Output HTML:

<input name="country" value="TW" />

As it is so common to use the name attribute's value as the bind attribute value, a shorthand was introduced in v3.4.1 allowing the single @ character to be used in place of @name.

Example HTML:

<input name="country" data-bind:value="@" />

Adding a question mark as the first character of the bind key can be used to toggle the presence of any attribute, depending on whether the bound value is truthy.

For example, data-bind:disabled="?deletedAt can be used to toggle the disabled attribute on the element when the deletedAt value is anything that loosely equals true.

HTML:

<button name="do" value="delete" data-bind:disabled="?deletedAt">Delete me</button>

PHP:

function example(DocumentBinder $binder, DateTime|null $deletedAt):void {
	$binder->bindKeyValue("deletedAt", $deletedAt);
}

Output HTML:

<button name="do" value="delete" disabled>Delete me</button>

or if the $deletedAt variable is null:

<button name="do" value="delete">Delete me</button>

The boolean modifier checks for a truthy value, but this can be inverted to check for a falsey value by adding an exclamation mark after the question mark. This is useful for when you only want to add an attribute when a value is falsey, for example data-bind:disabled="?!active" will add the disabled attribute when the active bind key is falsey.

The boolean modifier can also check for a specific value by adding an equals sign after the bind key.

This is useful when the bind key itself will always be truthy, but the attribute should only be added when the bound value matches a particular string.

Here we can see that the size bind key is used for all three radio buttons, but each one only becomes checked when the value of size matches its condition.

HTML:

<label>
	<input type="radio" name="size" value="s" data-bind:checked="?size=s" />
	<span>Small</span>
</label>
<label>
	<input type="radio" name="size" value="m" data-bind:checked="?size=m" />
	<span>Medium</span>
</label>
<label>
	<input type="radio" name="size" value="l" data-bind:checked="?size=l" />
	<span>Large</span>
</label>

PHP:

function example(DocumentBinder $binder, string $size):void {
	$binder->bindKeyValue("size", $size);
}

Output HTML when $size === "m":

<label>
	<input type="radio" name="size" value="s" />
	Small
</label>
<label>
	<input type="radio" name="size" value="m" checked />
	Medium
</label>
<label>
	<input type="radio" name="size" value="l" />
	Large
</label>

This syntax can be read as: "toggle this attribute when the bind key equals this value".

For example:

• data-bind:checked="?size=m" means "add checked when size is m"
• data-bind:selected="?country=GB" means "add selected when country is GB"

We've seen examples of both of these modifiers above. Did you know they can be combined? The checkbox example HTML above is synonymous with this:

<label>
	<input type="radio" name="size" value="s" data-bind:checked="?@name=@value" />
	<span>Small</span>
</label>
<label>
	<input type="radio" name="size" value="m" data-bind:checked="?@name=@value" />
	<span>Medium</span>
</label>
<label>
	<input type="radio" name="size" value="l" data-bind:checked="?@name=@value" />
	<span>Large</span>
</label>

?@name=@value expands to replace @name with the "name" of the input, and @value with its value. If you prefer to not repeat yourself, or if you might change the value of the input in the future, and only want to change on place, this feature might be useful.

It's possible to remove an element from the document when a certain condition is true/truthy by marking the element with the data-bind:remove attribute. If the boolean modifier is triggered, the element will be removed from the document.

The inverse logic can be applied by adding an exclamation mark (!) to the start of the bind value.

In this example, a bound object has an isDay boolean property, and the appropriate span is removed from the document, leaving the correct sentence behind:

<p id="day-or-night">Is it day or night? <span data-bind:remove="?isDay">It's nighttime!</span><span data-bind:remove="?!isDay">It's daytime!</span></p>

If the bound object has a truthy isDay property, the span containing "It's nighttime" will be removed, and the span containing "It's daytime" will persist.

Next, learn how to inject data into HTML with {{curly braces}}.