Binding lists

Repeating content is a common requirement when developing any web application: where an HTML element and its sub-tree repeats for every item in a list. It might be to output items of a to-do list, list users of the system, or show search results - all of these examples repeat HTML sub-trees to represent a list of items.

In your source HTML, to indicate that an element should be repeated for each item of a list, add the data-template attribute. Any element that has this attribute will be removed from the document, but the original position in the document will be remembered. Now you can call the bindList or bindListCallback function, passing in a list of data such as an array or other iterable, and for each item in the list the original template element will be cloned and added back into the document. The inserted element will be bound with whatever data is contained within the current iteration.

Note: in all examples in this section, we assume an HTMLDocument object is construced and passed to the DocumentBinder constructor. Learn more about constructing DomTemplate objects.

Simple example

This trivial example shows the basic concept by taking an array of strings that represent the days of the week and binding them to the <ul> element. Note that the <li> has the data-template attribute, along with data-bind:text to indicate that its textContent should be set to the value of each respective array item.

Source HTML:

<h1>Days of the week</h1>

<ul>
	<li data-template data-bind:text>Day</li>
</ul>

PHP:

function example(DocumentBinder $binder):void {
	$days = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
	$binder->bindList($days);
}

Output HTML:

<h1>Days of the week</h1>

<ul>
	<li>Monday</li>
	<li>Tuesday</li>
	<li>Wednesday</li>
	<li>Thursday</li>
	<li>Friday</li>
	<li>Saturday</li>
	<li>Sunday</li>
</ul>

Non-trivial example

Source HTML:

<h1>Top selling items</h1>

<ul>
	<li data-template>
		<a href="/shop/product/{{id}}">
			<img src="/product-image/{{id}}.jpg" alt="{{name}} product image" />
			<span class="name" data-bind:text="name">Product title</span>
			<p><span data-bind:text="currency">$</span><span data-bind:text="price">0.00</span></p>
		</a>
	</li>
</ul>

PHP:

function example(DocumentBinder $binder):void {
	$productList = [
		[
			"id" => 67,
			"name" => "Pot Plant",
			"currency" => "£",
			"price" => 8.95
		],
		[
			"id" => 20,
			"name" => "Umbrella",
			"currency" => "£",
			"price" => 11.99
		],
		[
			"id" => 74,
			"name" => "Wellington Boots",
			"currency" => "£",
			"price" => 15.00
		],
	];

	$binder->bindList($productList);
}

Output HTML:

<h1>Top selling items</h1>

<ul>
	<li>
		<a href="/shop/product/67">
			<img src="/product-image/67.jpg" alt="Pot Plant product image" />
			<span class="name">Pot Plant</span>
			<p><span>£</span><span>8.95</span></p>
		</a>
	</li>
	<li>
		<a href="/shop/product/20">
			<img src="/product-image/20.jpg" alt="Umbrella product image" />
			<span class="name">Umbrella</span>
			<p><span>£</span><span>11.99</span></p>
		</a>
	</li>
	<li>
		<a href="/shop/product/74">
			<img src="/product-image/74.jpg" alt="Wellington Boots product image" />
			<span class="name">Wellington Boots</span>
			<p><span>£</span><span>15.00</span></p>
		</a>
	</li>
</ul>

---

Next, learn how to bind tabular data into HTML tables.