Automatically remove unbound elements with `data‐element`

When an element has a data-bind attribute, if there is nothing bound to the element, the element's default content is preserved - this is a feature to allow an element's default state to be defined in the HTML.

It is sometimes useful to only display elements when they have data bound to them. A common example is when there's an error in a form; if there is no error message bound, the element containing the error message should ideally not exist anywhere in the document.

Similar to the data-list attribute that deals with a list of repeating elements, when dealing with single elements the data-element attribute can be added, which will automatically remove the element if it doesn't get bound before the cleanupDocument() function is called. In WebEngine applications, the document is cleaned automatically after your code has executed.

Example binding an error message to a form

Example html:

<h1>Log in to the system</h1>
<form method="post">

<!-- 
note this DIV is used to show an error with the form, but it should be removed
of there is no error bound by PHP.
-->

	<div data-element data-bind:text="error">Error message goes here</div>
	
	<label>
		<span>Your email address:</span>
		<input name="email" type="email" required />
	</label>
	<label>
		<span>Your password:</span>
		<input name="password" type="password" required />
	</label>
	
	<button name="do" value="login">Log in!</button>
</form>

Example PHP:

function example(
	DocumentBinder $binder,
	Input $input,
	Response $response,
	ExampleAuthentication $auth,
):void {
	try {
		$auth->login($input->getString("email"), $input->getString("password"));
		$response->redirect("/admin/settings/");
	}
	catch(ExampleAuthenticationException $e) {
		$binder->bindKeyValue("error", $e->getMessage());
	}
}

In the above example, the error message is defined in the HTML, but if there is no error, the element will be removed from the DOM automatically.

The PHP passes the example authentication system the user email and password, and if it succeeds, the user is redirected to the admin page.

If the authentication system throws an exception, the exception message is bound to the "error" bind key, and therefore the error message element is not removed from the page.

Using data-element with an attribute value to toggle the presence of an element

The above example has a data-element attribute without an attribute value. When data-element is used without a value, the data-bind attribute is used to decide whether or not to remove the element from the document - if the element is not bound, it will be removed.

Sometimes you may not have any data to bind, but would still like to toggle an element's presence. This can be done by adding the bind key to the data-element attribute itself. For example, <div data-element="error"> will be removed from the document if there is no error key bound, even though there is no data-bind attribute present.

In this case, only "truthy" bind values will prevent the element from being removed. "Falsey" bind values will still remove the element. This allows you to use a boolean or other truthy/falsey data type as the toggle.

Example only showing the certain elements to admin users:

HTML

<div class="panel">
	<p>You are logged in as <span data-bind:text="username">username</span></p>
	<p data-element="isAdmin">You are an administrator</p>
	<button name="do" value="save">Save record</button>
	<button data-element="isAdmin" name="do" value="delete">Delete record</button>
</div>

function example(
	DocumentBinder $binder,
	User $user,
):void {
	// Bind the "isAdmin" bind value. If the value is false, all data-elements of isAdmin will be removed.
	$binder->bindKeyValue("isAdmin", $user->isAdmin());
}

---

Next, learn how to bind tabular data into HTML tables.