DomTemplate

The following tweaks have been made to this minor patch release:

• null values can now be bound everywhere, without an exception being thrown.
• Internally, the term Modular has been renamed to Partial to reflect the actual usage and documentation.
• Another terminology change, cleanBindAttributes is renamed to cleanDatasets to better reflect what the function does.
• Examples are added to the source code for helping developers get used to the library.

This patch release introduces a bugfix, typehint improvements and a bump of dependencies:

• Improvements to bind list context https://github.com/PhpGt/DomTemplate/pull/275
• Typehint improvements https://github.com/PhpGt/DomTemplate/pull/273

In this patch release:

• Static analysis is improved: https://github.com/PhpGt/DomTemplate/pull/271
• "Partial" exceptions: https://github.com/PhpGt/DomTemplate/pull/270
• Clean data attributes: https://github.com/PhpGt/DomTemplate/pull/269

Full Changelog: https://github.com/PhpGt/DomTemplate/compare/v2.1.0...v2.1.1

This release is packed with small updates:

• bindListCallback is introduced that allows a callback function to be called on each iteration of the binding of a list, allowing you to mutate the data per element, along with manually tweaking the templated HTMLElement.
• BindableCache is introduced that significantly increases the speed of using Bind attributes.
• Wherever a bindable object is used, if it has an asArray function, it will always be called.
• It's now possible to leave a custom component empty without an exception being thrown.
• Overall, unit tests have been strengthened significantly.

In this minor patch release, bindData() will now check for all objects' Bind attribute, adding to the flexibility of throwing an object to a Document for binding to the HTML.

This release introduces no extra functionality, but changes the model in which the DOM is used, and how data is bound.

The major upgrade is that DOM v3 is now used, meaning that the DOM API is now more consistent with the W3C specification. With that, there are no longer any templating methods added to the DOM - instead there are specific classes that are used to bind data in different ways to different types of element. This is not only more readable, but enhances maintainability in your code by utilising the concept of dependency injection.

Have fun, and stay productive!

This patch release includes two improvements:

1. CI is handled by Github Actions now - you can check out the build history at https://github.com/PhpGt/Cli/actions

2. PHPStan level 6 has been applied to the code, meaning certain type hints have been improved for greater readability and future maintainability.

The following improvements have been made in this release:

• Docblock improvements to resolve the issue of nested properties losing their DomTemplate extensions (for example $document->getElementById("test")->parentNode->nextElementSibling should still be Gt\DomTemplate\Element, but was sometimes indicating Gt\Dom\Element.
• Dropped CircleCI for Github Actions - now everything is in once place (still to do: code quality scoring, currently handled by Scrutinizer)
• Bind attributes are removed in bulk at the end of the page render, which slightly improves performance, but mainly catches the error where not all attributes were removed.
  _ bindNames implemented, allowing form elements to have their values bound by their names.

Along with a dependency bump, this release brings the ability to bind the key of a key-value-pair data structure (such as an associative array) to a template element, with unnamed bind parameters.

Using the _key bind parameter will bind whatever the key is in a key-value-pair iterator. Nice for passing around associative arrays.

An example:

<ul>
  <li data-template> 
    Name: <span data-bind:text="_key">Person Name</span>, 
    Age: <span data-bind:text>0</span>
  </li>
</ul>

There are two improvements to how empty datasets are treated in this release:

1. When template elements are extracted from the document, but then are never bound to, the template parent elements have their innerHTML set to an empty string. A major benefit to this is that :empty is more reliable for using in CSS to display a message such as "This list has no entries yet".
2. Binding nested data where inner leaves are "empty" are treated in the same way when using bindNestedList as with bindList.

Have fun!

If an element has no children, and bindList() is called, passing in an empty dataset, the element has its innerHTML set to an empty string to clear up any hanging text fragments. This means that now, CSS's :empty pseudo-selector can be used to display an element differently when it has been bound with an empty dataset.

This release has two slight backwards-breaking changes:

1. Binding lists with bindList and bindNestedList can no longer use associative arrays for the data structure, because there is not any way of differentiating between an associative array and any other type of list of data structures. If you are using associative arrays, you will need to indicate that the array is actually a data structure and not a list by casting to an object. This is good practice anyway - arrays should only contain a list of things, objects can be used to describe data.
2. HTML components that have the data-template attribute on the component tag, rather than on the contained tag(s), can not be used if the component consists of multiple root elements. This is an edge-case and improves the readability by forcing component usage to be more expected.

Prior to this release, if you were to attempt to bind a boolean value somewhere in the DOM, a 0 or a 1 would be used as the value, which doesn't seem helpful in any way.

This release allows boolean values to behave slightly differently. Now, the boolean is used to define whether the bind value's key should be output to the element.

This is useful when a flag is required to be output to the DOM. For example, adding a class to an element when a navigation menu is "selected" or a to do item is "completed".

This technique can be used to bind a predefined value to an element only when the bind key is true. When a false value is bound, nothing will be bound to the DOM.

Example adding the "open" class to a <menu> element that already contains classes:

<menu class="main-menu positive" data-bind:class="open">
	...
</menu>

$document->querySelector("menu")->bindKeyValue("open", true);

• Only output t- prefix when there is a named template
• Introduce nullable name on getTemplate
• Simplify the mechanisms behind bind* functions
• Nullable lists

With this release, any data type can be used as the value to a bind function. This allows StdClass data objects, or any class with public properties to be used as the value to bind to the document.

This release is a bugfix that resolves an issue when multiple placeholders were present within the same attribute, using {curlyBrace} syntax.

The issue that has been resolved affected links with multiple paramters bound at once, for example, <a href="/user?id={userId}&type={userType}">Example</a>

When passing data to the bindData function of Bindable Elements, it has always been required for the data to be a key-value pair structure, or an object that implements BindDataMapper/Getter.

Now it is possible to pass any string-like value into bindData, and DomTemplate will attempt to perform implicit binding (binding to the DOM without using a named key).

• Document fragments are used when binding lists for efficiency.
• Return type of BindDataMapper can be any iterable object.
• BindDataGetter allows functions to be prefixed with "bind" rather than "get".
• Various PHPDoc comments have been overridden so allow IDEs to understand that DomTemplate versions of Nodes, Elements, Documents, etc. are being returned.
• A few small code refactorings which do not affect functionality.

Functionality of these two functions is too similar to justify having two separate functions. This release is backwards compatible - simply wrapping the functionality of bindNestedList into bindList, and bindNestedList is now currently deprecated. The function will be removed in v2 release, with all functionality handled within the bindList function.

A very small release here, changing the void return type from bindList to int, so you are informed of how many items were bound to the DOM.