Custom HTML components - PhpGt/WebEngine GitHub Wiki
Custom HTML components are provided as part of the DOM template repository, which is separately maintained at https://github.com/PhpGt/DomTemplate
The programming principal of "Don't Repeat Yourself" (DRY) aims to reduce the repetition of software patterns. As web developers we use the principal 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 within 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.
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).
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.
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 using DOM manipulation.
If the component consists of multiple root elements, all root elements will receive the class.
Within Page Logic classes, HTML elements can be treated as "template elements", as described in the section DOM templates, allowing the developer to clone the templates many times for outputting dynamic content.
Any custom HTML components within your project are also exposed as DOM templates, as the name of their component. To dynamically add a component to the page using PHP, first reference it with $element = $this->document->getTemplate("component-name");, and then add it to the page however you like, e.g. $document->body->appendChild($element);.
There are many ways to work with template elements, so continue reading the DOM templates section to learn more.