Skip to content

Binding nested lists

Jump to bottom
Greg Bowler edited this page Feb 21, 2023 · 22 revisions

In the previous section, we saw how to add data-template attributes to HTML elements to use them in bindList operations, but we only ever saw examples using one dimensional data.

Depending on your development style, or how your database supplies the data, you may want to provide the DocumentBinder with data structures that contain the entire dataset, including lists that contain other nested lists.

As an example of one possible data structure, let's use the idea of a user's music collection. The dataset consists of a list of Artists. Each Artist has a list of Albums. Each Album has a list of tracks. The data structure is three nested arrays:

/** @var array<string, array<string, array<string>>> $musicData */
$musicData = [
	"Artist1" => ["Album1" => ["Track1", "Track2", "Track3"], "Album2" => ["Track4", "Track5"]],
	"Artist2" => ["Album3" => ["Track1", "Track2", "Track3"]],
	// ... and so on ...
];
View a full example dataset with lots of real data

PHP:

/** @var array<string, array<string, array<string>>> $musicData */
$musicData = [
	"A Band From Your Childhood" => [
		"This Album is Good" => [
			"The Best Song You‘ve Ever Heard",
			"Another Cracking Tune",
			"Top Notch Music Here",
			"The Best Is Left ‘Til Last",
		],
		"Adequate Collection" => [
			"Meh",
			"‘sok",
			"Sounds Like Every Other Song",
		],
	],
	"Bongo and The Bronks" => [
		"Salad" => [
			"Tomatoes",
			"Song About Cucumber",
			"Onions Make Me Cry (but I love them)",
		],
		"Meat" => [
			"Steak",
			"Is Chicken Really a Meat?",
			"Don‘t Look in the Sausage Factory",
			"Stop Horsing Around",
		],
		"SnaxX" => [
			"Crispy Potatoes With Salt",
			"Pretzel Song",
			"Pork Scratchings Are Skin",
			"The Peanut Is Not Actually A Nut",
		],
	],
	"Crayons" => [
		"Pastel Colours" => [
			"Egg Shell",
			"Cotton",
			"Frost",
			"Periwinkle",
		],
		"Different Shades of Blue" => [
			"Cobalt",
			"Slate",
			"Indigo",
			"Teal",
		],
	]
];

In this example, we see each artist name as the key of the outer array, which contains an array of album tracks. The inner array's key represents the album name, and the value contains the list of tracks as an array of strings.

Because we are using either the array key or a plain string to represent the data, the HTML's bind attributes do not need to specify any bind keys.

HTML:

<!doctype html>
<h1>Music library</h1>

<ul>
	<li data-template>
		<h2 data-bind:text>Artist name</h2>
		
		<ul>
			<li data-template>
				<h3 data-bind:text>Album name</h3>
				
				<ol>
					<li data-template data-bind:text>Track name</li>
				</ol>
			</li>
		</ul>
	</li>
</ul>

To bind this data to the example HTML above, we can use bindList() and pass the array directly.

function example(DocumentBinder $binder, array $musicData):void {
	$binder->bindList($musicData);
}

Because the nesting of the data matches with the number of data-template elements, the lists will be bound to the appropriate HTML elements for each nested list.

Show the full HTML output. 
<!doctype html>
<h1>Music library</h1>

<ul>
	<li>
		<h2>A Band From Your Childhood</h2>

		<ul>
			<li>
				<h3>This Album is Good</h3>

				<ol>
					<li>The Best Song You‘ve Ever Heard</li>
					<li>Another Cracking Tune</li>
					<li>Top Notch Music Here</li>
					<li>The Best Is Left ‘Til Last</li>
				</ol>
			</li>
			<li>
				<h3>Adequate Collection</h3>

				<ol>
					<li>Meh</li>
					<li>‘sok</li>
					<li>Sounds Like Every Other Song</li>
				</ol>
			</li>
		</ul>
	</li>
	<li>
		<h2>Bongo and The Bronks</h2>

		<ul>
			<li>
				<h3>Salad</h3>

				<ol>
					<li>Tomatoes</li>
					<li>Song About Cucumber</li>
					<li>Onions Make Me Cry (but I love them)</li>
				</ol>
			</li>
			<li>
				<h3>Meat</h3>

				<ol>
					<li>Steak</li>
					<li>Is Chicken Really a Meat?</li>
					<li>Don‘t Look in the Sausage Factory</li>
					<li>Stop Horsing Around</li>
				</ol>
			</li>
			<li>
				<h3>SnaxX</h3>

				<ol>
					<li>Crispy Potatoes With Salt</li>
					<li>Pretzel Song</li>
					<li>Pork Scratchings Are Skin</li>
					<li>The Peanut Is Not Actually A Nut</li>
				</ol>
			</li>
		</ul>
	</li>
	<li>
		<h2>Crayons</h2>

		<ul>
			<li>
				<h3>Pastel Colours</h3>

				<ol>
					<li>Egg Shell</li>
					<li>Cotton</li>
					<li>Frost</li>
					<li>Periwinkle</li>
				</ol>
			</li>
			<li>
				<h3>Different Shades of Blue</h3>

				<ol>
					<li>Cobalt</li>
					<li>Slate</li>
					<li>Indigo</li>
					<li>Teal</li>
				</ol>
			</li>
		</ul>
	</li>
</ul>

Using the data-bind:list attribute

// TODO

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

PHP.Gt/DomTemplate is a separately maintained component of PHP.Gt/WebEngine.

Binding data

HTML functionality

More information

Clone this wiki locally