Bind properties and modifiers
Most data-bind:* attributes set an element attribute or property, but some bind properties and modifier characters add extra behaviour.
Common bind properties
Here are the bind properties we will use most often:
textsetstextContenthtmlsetsinnerHTMLvaluesets form valuesclassadds or toggles class nameslistbinds a nested iterable into a contained list templatetablebinds table data into a<table>removeremoves an element conditionally- any other property name is treated as a normal attribute name
Bind expressions can also apply bind filters before the property or modifier receives the value, for example data-bind:text="amount|numericOutput".
text and html
HTML:
<p data-bind:text="name">Guest</p>
<div data-bind:html="bioHtml">Plain text bio</div>
If we bind name, the element’s text content changes. If we bind bioHtml, the element’s inner HTML changes.
[!IMPORTANT]
htmlinserts HTML, so it should only be used with trusted content to avoid cross-site scripting (XSS). If we’re only using plain text, stick totext.
class
Without a modifier, data-bind:class adds one or more class names.
HTML:
<div class="panel" data-bind:class="extraClass"></div>
If we bind extraClass to featured, the element ends up with class="panel featured".
If the bound value contains multiple class names separated by spaces, each one is added individually.
HTML:
<div class="panel" data-bind:class="stateClasses"></div>
PHP:
$binder->bindKeyValue("stateClasses", "featured compact");
Output HTML:
<div class="panel featured compact"></div>
Arrays of strings are supported here too, so you can pass an array such as ["featured", "compacts"] and DomTemplate will add the class names in the array.
The : token modifier
The colon modifier toggles a token within a token list, most commonly a class name.
HTML:
<li data-bind:class=":isSelected selected"></li>
If isSelected is truthy, selected is added. If it is falsey, selected is removed.
We can also toggle several classes together:
<li data-bind:class=":isSelected selected featured"></li>
If isSelected is truthy, both selected and featured are added. If it is falsey, they are both removed.
If we omit the explicit token name:
<li data-bind:class=":status"></li>
a boolean value toggles the class with the same name as the bind key: true adds status, and false removes it. For other values, the bound value itself supplies the tokens. This also works with several class names:
$binder->bindKeyValue("status", "featured compact");
In that case, both featured and compact are toggled together.
Toggle classes independently
A single data-bind:class attribute can contain several binding expressions separated by spaces:
HTML:
<span class="weight" data-bind:class=":overweight :oversize">0,000</span>
PHP:
$binder->bindKeyValue("overweight", true);
$binder->bindKeyValue("oversize", true);
Both classes are added, preserving the existing weight class. The keys can be bound in either order.
Each new modifier starts another expression. Class names without a modifier belong to the preceding expression, so we can also write:
<span data-bind:class=":overweight heavy warning :oversize bulky">0,000</span>
Here overweight toggles heavy and warning together, while oversize independently toggles bulky.
The inverse token modifier
If we want to toggle a token when a value is falsey rather than truthy, we can add ! alongside :.
HTML:
<li data-bind:class=":!isVisible hidden"></li>
Here we can read it as: “add hidden when isVisible is not truthy”.
The order of the modifier characters does not matter, so !: works in the same way as :!:
<li data-bind:class="!:isVisible hidden"></li>
The ? boolean modifier
The question mark toggles an attribute based on truthiness.
HTML:
<button data-bind:disabled="?isArchived">Archive</button>
If isArchived is truthy, the button gets disabled. Otherwise, that attribute is removed.
The ?! inverse boolean modifier
HTML:
<button data-bind:disabled="?!isEditable">Save</button>
Here we can read it as: “disable the button when isEditable is not truthy”.
The order does not matter here either, so !? works in the same way as ?!:
<button data-bind:disabled="!?isEditable">Save</button>
Boolean equality checks with =
We can also make the boolean modifier compare against a specific string value.
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>
If size is "m", the middle radio becomes checked.
This is especially handy for radios, tab state, and selected options.
The @ attribute reference modifier
The @ modifier lets us reuse an existing attribute value instead of repeating ourselves.
HTML:
<input name="email" data-bind:value="@name" />
This behaves as though we had written:
<input name="email" data-bind:value="email" />
There is also a shorthand:
<input name="email" data-bind:value="@" />
which means the same thing as @name.
Combining modifiers
Modifiers can be combined in one expression.
HTML:
<input
name="size"
value="m"
data-bind:checked="?@name=@value"
data-rebind />
Here we are saying:
- look up the bind key from
name - compare it with the current element’s
value - add
checkedwhen they match
We can also bundle several modifier expressions for the same property by separating them with semicolons:
<div data-bind:class=":isSelected selected; :isAdmin admin"></div>
Mixing modifiers in class bindings
Space-separated class expressions also support ? and inverse modifiers, including :!, !:, ?! and !?:
<div data-bind:class="?isAdmin :featured !?loggedIn"></div>
Each expression keeps its usual behaviour. : adds or removes individual class tokens. ? sets or removes the entire class attribute: binding isAdmin to "admin" sets class="admin", while a falsey value removes the attribute. !?loggedIn removes the entire attribute when loggedIn is truthy. A later whole-attribute binding can therefore replace or remove classes added by an earlier binding.
For independently toggled classes, use colon modifiers instead:
<div data-bind:class=":isAdmin admin :!loggedIn guest" data-rebind></div>
This toggles admin when isAdmin is truthy and guest when loggedIn is falsey, preserving unrelated classes. With data-rebind, either key can be bound again to update its classes.
Space-separated modifier expressions are supported for data-bind:class. For other bind properties, separate multiple expressions with semicolons.
data-rebind
By default, DomTemplate removes each expression after its key has been bound. If other expressions remain in the attribute, they stay available until their keys are bound. Once all expressions have been used, the bind attribute is removed.
If we want the property to remain bindable, add data-rebind.
HTML:
<button data-bind:disabled="?isBusy" data-rebind>Save</button>
This is useful when we bind the same area more than once during one request.
data-bind:remove
remove is a special bind property that removes the element itself rather than mutating one of its attributes.
HTML:
<p>
<span data-bind:remove="?isDay">It's night-time.</span>
<span data-bind:remove="?!isDay">It's daytime.</span>
</p>
If isDay is true, the first span disappears. If isDay is false, the second span disappears.
data-bind:list
This property binds a nested iterable into a child list template.
HTML:
<section data-bind:list="orderList">
<ul>
<li data-list data-bind:text="id">Order</li>
</ul>
</section>
When the key orderList is bound, the contained list template is used.
We will cover that properly in the binding lists section.
data-bind:table
This property tells DomTemplate where table-shaped data should go.
HTML:
<table data-bind:table="sales"></table>
We will go through the supported table data shapes in the binding tables section.
Now that the element-level behaviour is clear, move on to binding lists for the part of the library that does the heavy lifting with repeated markup.