Skip to content

Home

Jump to bottom
Greg Bowler edited this page Apr 14, 2026 · 28 revisions

Built on top of PHP.GT/Dom, this project provides dynamic data binding to DOM Documents, document templating, and reusable HTML components.

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

HTML can be made dynamic with data-bind and data-list attributes, placeholders such as {{name}}, reusable <custom-components>, and partial page templates.

Why not just use DOM to manipulate the page?

The layers of your application should ideally have a strong separation of concerns. The layers are often described as the Model, View, and Controller - referred to as MVC architecture. In MVC, the Model represents the application's data, the View is the HTML user interface, and the Controller contains the PHP application logic that binds data from the Model to the View.

A strong separation of concerns means that HTML view and PHP logic are not tightly coupled. Changes to the HTML structure should not require changes to the PHP data-binding logic. When PHP code directly manipulates the DOM, the HTML and PHP become closely tied together. As a result, even small changes to the HTML can break existing PHP code and force updates whenever the page structure is edited. Data binding helps avoid this problem.

By binding data through the data-bind:* attributes introduced by DomTemplate, we can create HTML view files that are more readable, maintainable, and loosely coupled to the PHP controller logic. This means the layout and structure of the HTML can change signifciantly without requiring changes to the PHP code.

An example of what using this project looks like in your HTML:

<!-- 
extends=base-page

[vars]
title=Your order 
-->

<!--
The INI syntax at the start of an HTML file can be used to configure "partial" views.
You can quickly see that this page extends the template provided by base-page.html and
that the `title` is set to Your order. This var can be referred to by the base-page,
setting the page title, for example.
-->

<h1>Your order</h1>

<!-- here is a custom element maintained in its own checkout-list.html -->
<checkout-list />

<p>The order total is <span data-bind:text="priceFormatted">£0.00</span></p>
<p>Items in your order:</p>
<ul>
<!-- the li is marked with data-list so it repeats for every row of a data source -->
	<li data-list>
<!-- the content of the li is clearly marked to show what data to bind -->
		<span data-bind:text="name">Item Name</span>
		<span data-bind:text="priceFormatted">£0.00</span>
	</li>
</ul>

In the above example, the HTML can be maintained completely separately to the PHP, promoting a strong separation of concerns. The entire HTML structure can change, without having to communicate this to PHP, as long as the data-bind:* and data-list attributes are applied to the appropriate elements. This is what's referred to as loosely coupled code - the page logic is loosely coupled to the page view, leading to highly maintainable systems.

Note

If you are building with WebEngine, this library is provided ready to use without setup. The framework constructs the binder objects, expands partials and components automatically, and cleans the document after your page logic runs.

What this library does

  • Binds scalar values and key/value data to HTML elements.
  • Repeats sections of markup from iterable data.
  • Binds nested objects and iterable objects to corresponding HTML structure.
  • Builds tables from several compatible data structures.
  • Expands custom HTML components from separate files.
  • Extends page templates using partial HTML documents.

Recommended reading order

  1. Overview
  2. Getting started
  3. Binding basics
  4. Bind properties and modifiers
  5. Binding lists
  6. Binding objects
  7. Binding tables
  8. Conditional and optional elements
  9. HTML components
  10. Partials
  11. Debugging
  12. API reference

A simple example

<!doctype html>
<h1>Hello, <span data-bind:text="name">you</span>!</h1>
use GT\Dom\HTMLDocument;
use GT\DomTemplate\BindableCache;
use GT\DomTemplate\DocumentBinder;

function example(DocumentBinder $binder):void {
	$binder->bindKeyValue("name", "Cody");
	$binder->cleanupDocument();
	echo $document;
}

Output HTML:

<!doctype html>
<h1>Hello, <span>Cody</span>!</h1>

In a nutshell: the HTML says what can change, the PHP supplies the data, and DomTemplate joins the two together.

To see the whole shape of the library before we start wiring it up, move on to Overview.

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

Clone this wiki locally