Releases: PhpGt/DomTemplate
More improvements to handling empty data
There are two improvements to how empty datasets are treated in this release:
- 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". - Binding nested data where inner leaves are "empty" are treated in the same way when using
bindNestedList
as withbindList
.
Have fun!
Binding an empty dataset respects :empty selector
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.
Improved component/template relationship
This release has two slight backwards-breaking changes:
- Binding lists with
bindList
andbindNestedList
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. - 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.
Bindable booleans
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);
Minor general improvements
- Only output t- prefix when there is a named template
- Introduce nullable name on
getTemplate
- Simplify the mechanisms behind bind* functions
- Nullable lists
Bindable objects
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.
Multiple parameter placeholders
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>
Implicit binding using bindData function
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).
Minor improvements
- 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.
Consolodate bindList and bindNestedList
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.