Data changes

Bindary updates the view when it knows something changed. Usually it works that out itself, because the data containers are observed. This page is about the cases where you tell it instead and about describing a change precisely enough that a large collection does not have to re-render.

The automatic case

Assignments to appData, routeData and viewData are picked up through native Proxies, so ordinary JavaScript is enough and nothing on this page is needed.

$bindary.appData.order.total = 49.95;   // the view follows

This is on by default, controlled by $bindary.observing. Turn it off with $bindary.stopObserving(), back on with $bindary.startObserving(), useful when you're about to make a batch of changes and want one update at the end rather than one per mutation.

Registering a change yourself

Three methods, differing only in how they identify what changed. These only do something useful when observing is off or when the data lives somewhere Bindary was never watching in the first place, calling one of these against a plain appData mutation while observing is on registers a change that was already going to happen anyway.

$bindary.dataChange(dataKey, container) names the path that changed.
$bindary.dataChangeForModel(model) names the object itself, by reference.
$bindary.dataChangeForId(updateId) names one element through its update-id.

Each updates the view straight away. Pass false as the last argument to hold that back and call $bindary.updateView() yourself once a batch is complete.

$bindary.dataChange('order.lines', 'appData');
$bindary.dataChangeForModel($bindary.appData.order);
$bindary.dataChangeForId('orderTotal');

For an object of your own that should be watched going forward rather than registered by hand every time, $bindary.observe() is usually the better answer, see component file for it used on a component's own property.

Describing what happened to an array

Knowing that a collection changed is not the same as knowing how. Without more detail the safe assumption is that everything in it might be different and every row gets reconsidered. Array update rules let you say exactly what moved, so the rest is left alone.

// three rows inserted at position 5, everything else untouched
$bindary.dataChange('order.lines', 'appData', [{ addIndex: 5, addCount: 3 }]);

// row 2 changed in place
$bindary.dataChange('order.lines', 'appData', [{ keys: [2] }]);

// row 2 changed and its element should be rebuilt rather than reused
$bindary.dataChange('order.lines', 'appData', [{ keys: [2], recreate: true }]);

keys: indexes or keys of items that changed.
recreate: rebuild the element for those items instead of updating it.
addIndex and addCount: where and how many items were added. Omit the index when they were appended.
removeIndex and removeCount: the same for removals.

This is where the difference shows on large collections. Re-rendering a thousand rows because one of them moved is the thing worth avoiding and the rules are how you avoid it.

Clearing registered changes

$bindary.clearDataChanges() drops every currently registered change and cancels a pending delayed update. Rarely needed directly, mostly relevant if you're building something that manages its own update timing.

Holding server data back

$bindary.lock() and $bindary.unlock() are specifically for data arriving from the server over a connected route, a WebSocket push or an XHR response, not for changes you make yourself in ordinary code. Locking postpones applying an incoming update for a data-key, a container or everything, until the matching unlock() call, rather than letting it land the moment it arrives.

The case this exists for: a server update lands while the user is in the middle of editing a form bound to that same data. Letting it apply immediately means their in-progress edit gets overwritten mid-keystroke. Locking that key while they're editing, unlocking when they're done, is how you avoid that collision.

$bindary.lock('order.customerName', 'appData'); // user is editing this field
// ...
$bindary.unlock('order.customerName', 'appData'); // done editing, apply anything that arrived meanwhile

dataContainer defaults to viewData, not appData, when only dataKey is given. Lock a path under appData and forget to specify the container, and you've locked the same-named path under viewData instead.

Example

appData is observed by default, so simply assigning data.value2 below would already trigger the update on its own, nothing left to demonstrate. To actually show the manual methods doing real work, this example turns observing off for the moment of the assignment, then registers the change explicitly afterward. In your own code you'd only do this when the data genuinely isn't being watched, this is purely to make the mechanism visible.