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

// TODO intro paragraph.

The data-template attribute

Outputting template elements for each row of data

// TODO.

Unnamed data-template attributes

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

The data-bind attribute and the bind function

// 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.

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.

Outputting data to placeholder elements

// TODO.

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 | Github

Introduction

Tutorials

User guide

Further reading

Setup guides

Clone this wiki locally