PHP.GT

Getting started

In this section we will build the smallest useful DomTemplate setup from scratch.

The main thing to know is that DocumentBinder is the public entry point, but it relies on a few smaller helper objects behind the scenes. Once those are wired together, we can bind values, lists, tables, components, and partials in a consistent way.

[!TIP] In WebEngine, you usually do not instantiate these objects yourself. The framework builds and injects them for you.

1. Install the library

composer require phpgt/domtemplate

2. Create an HTMLDocument

use Gt\Dom\HTMLDocument;

$html = <<<'HTML'
<!doctype html>
<h1>Hello, <span data-bind:text="name">you</span>!</h1>
HTML;

$document = new HTMLDocument($html);

DomTemplate works with HTMLDocument from phpgt/dom, so this is always our starting point.

3. Construct the binder’s dependency tree

Each piece of functionality within DomTemplate is controlled by a separate class. Here we’ll build up the dependency tree, so all classes are aware of each other in a way that respects object oriented encapsulation:

use GT\DomTemplate\BindableCache;
use GT\DomTemplate\DocumentBinder;
use GT\DomTemplate\ElementBinder;
use GT\DomTemplate\HTMLAttributeBinder;
use GT\DomTemplate\HTMLAttributeCollection;
use GT\DomTemplate\ListBinder;
use GT\DomTemplate\ListElementCollection;
use GT\DomTemplate\PlaceholderBinder;
use GT\DomTemplate\TableBinder;

$elementBinder = new ElementBinder();
$placeholderBinder = new PlaceholderBinder();
$tableBinder = new TableBinder();
$listBinder = new ListBinder();
$listElementCollection = new ListElementCollection($document);
$bindableCache = new BindableCache();
$htmlAttributeBinder = new HTMLAttributeBinder();
$htmlAttributeCollection = new HTMLAttributeCollection();

$elementBinder->setDependencies(
	$htmlAttributeBinder,
	$htmlAttributeCollection,
	$placeholderBinder,
);
$htmlAttributeBinder->setDependencies($listBinder, $tableBinder);
$listBinder->setDependencies(
	$elementBinder,
	$listElementCollection,
	$bindableCache,
	$tableBinder,
);
$tableBinder->setDependencies(
	$listBinder,
	$listElementCollection,
	$elementBinder,
	$htmlAttributeBinder,
	$htmlAttributeCollection,
	$placeholderBinder,
);

$binder = new DocumentBinder($document);
$binder->setDependencies(
	$elementBinder,
	$placeholderBinder,
	$tableBinder,
	$listBinder,
	$listElementCollection,
	$bindableCache,
);

That looks like quite a lot at first glance, but we only have to set it up once. After that, all normal binding goes through $binder.

4. Bind some data

$binder->bindKeyValue("name", "Cody");

At this point the document contains the updated text, but it still contains the original DomTemplate attributes too.

5. Clean the document

$binder->cleanupDocument();
echo $document;

cleanupDocument() removes helper attributes such as data-bind, data-list, data-template, and data-element from the output. It also removes unbound optional elements marked with data-element.

Output HTML:

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

6. Know which binder to use

Most of the time, DocumentBinder is the right tool.

  • Use DocumentBinder when working on the whole page.
  • Use ComponentBinder when working inside a single expanded component.

ComponentBinder has the same binding methods, but it automatically limits the bind scope to one component element.

[!NOTE] In WebEngine, you can just use Binder instead of ComponentBinder or DocumentBinder and you’ll be given the correct instance depending on the context in which you’re using it. Within a page’s PHP you’ll get the DocumentBinder and within a component’s PHP you’ll get the ComponentBinder.

7. Optional page composition helpers

If we are also using component files or partial templates, there are two extra helpers:

  • ComponentExpander expands custom HTML elements from a component directory.
  • PartialExpander applies a page template from a partial directory.

Those are covered properly later in HTML components and Partials.

Our binder is now wired up. Next we can learn the core public API in Binding basics.