Skip to content

DOM Templates

Jump to bottom Edit New page
Greg Bowler edited this page Jun 13, 2018 · 28 revisions

The DOM template repository is separately maintained at https://github.com/PhpGt/DomTemplate

A core concept of developing WebEngine applications is the use of the Document Object Model (DOM). WebEngine exposes the page's DOM to your code as described in DOM manipulation. The DOM implementation aims to be as standards compliant as possible, matching the APIs you'd expect to see in client side code.

Directly manipulating the DOM in your code can lead to tightly coupling the logic and view. As a powerful solution, binding data using custom elements and data attributes leads to highly readable, maintainable view files that are loosely coupled to the application logic.

Custom HTML components

The programming principal of "Don't Repeat Yourself" (DRY) aims to reduce the repetition of software patterns. As web developers we use it all the time with object oriented programming, writing code once that can be reused elsewhere.

When writing HTML, it is common to build complex components out of multiple elements such as menus, concertinas and popup windows, and it would be great to adhere to the DRY principal with HTML. There are upcoming standards to implement HTML templates in the browser, but having template functionality available on the server allows your application's logic to prerender all page content before the browser has to download a single byte.

Custom HTML components look <like-this> and allow developers to create their own HTML tags, and reuse them across their whole application.

At render time, custom components will be replaced with their expanded HTML. To define a component, create a file named with the component's name in the page/_component directory, and then reference its name in an HTML tag anywhere within the application's HTML to use it.

Example <main-menu> component:

page/_component/main-menu.html:

<ul>
	<li>
		<a href="/">Home</a>
	</li>
	<li>
		<a href="/about">About</a>
	</li>
	<li>
		<a href="/contact">Contact</a>
	</li>
</ul>

page/index.html:

<!doctype html>
<html>
<head>
	<meta charset="utf-8" />
	<title>Custom component example</title>
</head>
<body>
	<main-menu></main-menu>

	<article>
		<h1>Look at the main menu above!</h1>
		<p>...</p>
	</article>
</body>
</html>

In the example above you can see the use of the <main-menu> tag and how its contents is defined within the matching src/page/_component/main-menu.html file.

The <main-menu> tag will be replaced with the contents of the main-menu.html component file. A class will be added to the element allowing you to reference it by its original component name in PHP and CSS (see below).

What are valid names for custom components?

A component must have a hyphen in its name. This requirement is defined by the Worldwide Web Consortium (W3C) and is imposed so that no matter what you name your custom components, they will never clash with any future version of HTML's tags. Components without a hyphen in their names will not be loaded.

Referencing components in PHP or CSS

After a component has been loaded and its custom tag has been replaced, the root element(s) of the component will have their component name added to the class attribute, prefixed with c-.

For example, the <main-menu> component mentioned above will be replaced with the <ul> contained within the component's html source. The replacement element will have the class c-main-menu added, allowing you to reference it with the .c-main-menu CSS selector.

If the component consists of multiple root elements, all root elements will receive the class.

HTML templates

The concept of HTML templates introduces special elements that are extracted from the DOM before the page is rendered, and supplied to your PHP code, allowing you to clone the template elements multiple times across the page. This is useful for building up lists of repeating content, or for hiding/displaying content depending on certain circumstances.

There are multiple methods of using templates within WebEngine, as described below.

The data-template attribute

The simplest way to extract an element as a template is to add the data-template attribute to the element. Elements with this attribute are extracted out of the DOM before the page is rendered and are stored in the DOM's template list for easy referencing in PHP.

The value of the data-template attribute is the name of the template. In PHP you can obtain a clone of the template element by its template name. As the element is extracted from the DOM, it will retain a reference of its original parent, allowing you to insert the template back in-place with the insertTemplate() function.

Example:

<h1>Shopping list:</h1>

<ul>
	<li data-template="product">Product name</li>
</ul>
public function go() {
	$li = $this->document->getTemplate("product");
	$li->innerText = "Coffee";
	$li->insertTemplate();
}

Outputting template elements for each row of data

Assuming you have an iterable collection of data such as an array, dynamic lists can easily be built up by using getTemplate within loops.

For example, having an array of items in a shopping list, the above <ul> element can have an <li> added for each element in the array:

public function go() {
	$shoppingList = ["Coffee", "Baked Beans", "Bread"];

	foreach($shoppingList as $item) {
		$li = $this->document->getTemplate("product");
		$li->innerText = $item;
		$li->insertTemplate();
	}
}

The outputting HTML will be as follows:

<h1>Shopping list:</h1>

<ul>
	<li class="t-product">Coffee</li>
	<li class="t-product">Baked Beans</li>
	<li class="t-product">Bread</li>
</ul>

Binding data to placeholder elements

Using standard DOM techniques it's possible to output data from PHP to the HTML, without echoing strings of HTML, by using the proper APIs, such as setting elements' innerText or value.

However, accessing the DOM directly can lead to tightly coupled code, meaning that your PHP code may break if the HTML is altered at a later date. A better way to bind data to an element is to use the data-bind attribute on the element.

Any element that you wish to output dynamic data to can have the data-bind attribute added. The syntax of this attribute is the following:

data-bind:x=y, where x is the property to bind to, and y is the data key to use.

For example, with the following HTML source:

<div id="output">
	<h1 data-bind:text=title>Page title</h1>
	<p data-bind:text=content>Page content</p>
</div>

and the following PHP logic:

public function go() {
	$data = [
		"title" => "How to bind data",
		"content" => "It's quite simple really",
	];

	$this->document->getElementById("output")->bind($data);
}

will produce the following HTML output:

<div id="output">
	<h1>How to bind data</h1>
	<p>It's quite simple really</p>
</div>

The data-bind attribute and the bind function

Iterating over datasets manually and inserting templates in code is useful for only simple applications. In real world applications, the template element may have many children, and setting the data on the children manually can lead to tightly coupled code.

Rather than iterating

Example of a more advanced template:

<h1>Employee list:</h1>

<ul>
	
</ul>

// TODO: text/html synonyms for innertext/innerhtml (attribute keys have to be lowercase).

// TODO: text, html, value treated specially... otherwise data is bound to the attribute specified.

Unnamed data-template attributes

// TODO: bind function will clone the element for each row of data.

Using components as templates

// TODO: more info on below paragraph.

Templates are loaded by name, and it is possible to reference a component as a template by the component name.

For example:

$mainMenuTemplate = $this->document->getTemplate("main-menu");

Components that are added to the page as a template will receive the c- prefixed class name along with a t- prefixed class name, indicating that they were added as a template.

Binding data within attributes using {curly braces}

// TODO: Curly avoided to prevent reinventing markup language, unavoidable when data is to be bound within attributes.

Website | Packagist | CircleCI | Scrutinizer

Introduction

Tutorials

User guide

Further reading

Setup guides

Clone this wiki locally