v2 (#229)

* remove all obsolete classes * upgrade dependencies * feature: DataBinder::bindValue() * tweak: update exception messages * tweak: remove unused imports * refactor: share functionality for setting bind property * refactor: simplify functionality * refactor: rename to DocumentBinder * tweak: rename test function names * refactor: simplify nested foreach * docs: update features * tweak: import fqn * refactor: remove ott checks for invalid properties * feature: bindData * feature: DocumentBinder::bindData() toggles DOMTokenList values * feature: DocumentBinder::bindData() toggles boolean values * feature: DocumentBinder::bindData() toggles boolean values with inverse logic from ! char * feature: binding tabular data to a table element * wip: table data normalisation * feature: normalise table data * feature: implement "double header" table data * test: exception if indexed array passed to bindData * test: bindData with stdClass object * test: bindKeyValue with incorrect table data * test: bindKeyValue with non-iterable double header table data * tweak: change data type to int in example * test: bindKeyValue throw error when tableData is assoc without iterable cols * test: bindKeyValue throw error when binding tableData with no table in html * wip: add todos to get bindTable to 100% * test: various table tests to ensure table data is normalised correctly * test: bindTable with header keys in the HTML * tweak: remove unused code * refactor: extract table binding into separate class * test: bindKeyValue with table data * tidy: remove unused imports * tidy: more accurate test names * refactor: extract element-specific binding to ElementBinder * feature: ListBinder basic list bound to document * feature: ListBinder binds text from values * feature: ListBinder binds templates by name * test: better working with empty lists * feature: binding an empty list will clear the innerHTML of the template's parent * test: binding a table to the document, rather than a specific element * feature: bind list of key-value-pair arrays * feature: bind list of key-value-pair objects * feature: bind list of key-value-pair instance objects * feature: Bind attribute used to mark methods/properties as dom-bindable * feature: get a template element by its document position * feature: throw exception if matching template is not found * feature: get template element by template name * feature: throw exceptions when names are not set correctly * feature: bind text placeholder * test: bind text placeholder's context does not leak * feature: remove filtering feature from HTML * feature: placeholders within attributes * tweak: more appropriate naming * improvement: binding nested elements resolve their template parents properly * feature: nested lists with implicit keys * refactor: update bind model - extract placeholder binding to separate classes * feature: complete refactor of PlaceholderBinder * test: DocumentBinder::bindList() * test: HTMLAttributeBinder::bind() with Document context * tweak: rename context to element when not performing a child search * test: ListBinder::isKVP() * chore: remove unused function * chore: remove obsolete conditional * test: ensure template names can't start with a forward slash * chore: work through PHPStan's issues * test: add a real-world test for todo items * test: ensure template's siblings are not also templates * feature: parse ini data within comments * tweak: document type of array * feature: expand custom elements * feature: expand custom elements recursively * feature: expand partials * test: harden test cases * wip: recursive partial expansion * feature: recursive partial expansion * feature: recursive partials import deepest title * chore: update deps * chore: update deps * phpstan: fix generics issue * remove unused test (from v1) * build: upgrade deps
PhpGt · Sep 8, 2021 · 08cf2d3 · 08cf2d3
1 parent f6db2f8
commit 08cf2d3
Show file tree

Hide file tree

Showing 88 changed files with 4,046 additions and 3,880 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Bind dynamic data to reusable HTML components.
 
-Built on top of [PHP.Gt/Dom][dom], this project provides simple view templating and dynamic data binding.
+Built on top of [PHP.Gt/Dom][dom], this project provides dynamic data binding to DOM Documents, document templating and reusable HTML components.
 
 Directly manipulating the DOM in your 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.  
 
@@ -22,79 +22,51 @@ Directly manipulating the DOM in your code can lead to tightly coupling the logi
 	<img src="https://badge.status.php.gt/domtemplate-docs.svg" alt="PHP.G/DomTemplate documentation" />
 </a>
 
-## Example usage: Bind dynamic data to a template element
+## Example usage: Hello, you!
 
-Consider a page with an unordered list (`<ul>`). Within the list there should be a list item (`<li>`) for every element of an array of data.
+Consider a page with a form, with an input element to enter your name. When the form is submitted, the page should greet you by your name.
 
-In this example, we will simply use an array to contain the data, but the data can come from a data source such as a database, as long as it is `iterable`.
+Without submitting the form, the HTML will be rendered untouched, showing the default message "Hello, you!".
 
-### Source HTML ([`01-groceries-example.html`][example-groceries-html])
+### Source HTML (`name.html`)
 
 ```html
 <!doctype html>
-<h1>Shopping list</h1>
-
-<shopping-list id="groceries"></shopping-list>
-
-<p>The use of a custom element is more useful on more complex pages, but is shown above as an example.</p>
+<h1>
+	Hello, <span class="name-output">you</span>!
+</h1>
+
+<form>
+	<input name="name" placeholder="Your name, please" required />
+	<button>Submit</button>
+</form>
 ```
 
-### Custom element HTML (`_component/shopping-list.html`)
-
-```html
-<ul>
-	<li data-template data-bind:text="title" data-bind:data-id="id">Item name</li>
-</ul>
-```
-
-### PHP used to inject the list
+### PHP used to inject your name (`name.php`)
 
 ```php
 <?php
 require "vendor/autoload.php";
 
-use Gt\DomTemplate\HTMLDocument;
-
-$html = file_get_contents("example.html");
-$document = new HTMLDocument($html, "./_component");
-$document->extractTemplates();
+$html = file_get_contents("name.html");
+/** @var \Gt\Dom\HTMLDocument $document */
+$document = \Gt\Dom\Facade\HTMLDocumentFactory::create($html);
 
-$data = [
-	["id" => 1, "title" => "Tomatoes"],
-	["id" => 2, "title" => "Noodles"],
-	["id" => 3, "title" => "Cheese"],
-	["id" => 4, "title" => "Broccoli"],
-];
+if($name = $_GET["name"]) {
+	$binder = new \Gt\DomTemplate\DocumentBinder($document);
+	$binder->bindKeyValue("name-output", $name);
+}
 
-$outputTo = $document->getElementById("groceries");
-$outputTo->bindList($data);
+echo $document;
 ```
 
-### Output:
-
-```html
-<!doctype html>
-<h1>Shopping list</h1>
-
-<shopping-list>
-    <ul id="shopping-list">
-        <li data-id="1">Tomatoes</li>
-        <li data-id="2">Noodles</li>
-        <li data-id="3">Cheese</li>
-        <li data-id="4">Broccoli</li>
-    </ul>
-</shopping-list>
-
-<p>The use of a custom element is more useful on more complex pages, but is shown above as an example.</p>
-```
 
 Features at a glance
 --------------------
 
-+ HTML components - organise and reuse DOM trees by storing separate components in their own HTML files, and including them using custom HTML tags.
 + Binding of dynamic data - bind key value pairs, associative arrays, lists of associative arrays and even nested lists.
-+ Use standards compliant techniques for templates and components.
-+ Easily style components using CSS by addressing their tag name (`shopping-list` in the above example).
++ HTML components - organise and reuse DOM trees by storing separate components in their own HTML files, and including them using custom HTML tags.
++ Page templates - create HTML documents that "extend" others.
++ Easily modularise CSS by selecting their custom tag names.
 
 [dom]: https://www.php.gt/dom
-[example-groceries-html]: https://github.com/PhpGt/DomTemplate/blob/master/example/01-example-groceries.html
diff --git a/composer.json b/composer.json
@@ -4,8 +4,9 @@
 	"license": "MIT",
 
 	"require": {
+		"php": ">=8.0",
 		"ext-dom": "*",
-		"phpgt/dom": "2.*"
+		"phpgt/dom": "v3.0.0-RC2"
 	},
 	"require-dev": {
 		"phpunit/phpunit": "9.*",
@@ -21,5 +22,12 @@
 		"psr-4": {
 			"Gt\\DomTemplate\\Test\\": "./test/phpunit"
 		}
-	}
+	},
+
+	"funding": [
+		{
+			"type": "github",
+			"url": "https://github.com/sponsors/PhpGt"
+		}
+	]
 }