Bindary

Bindary binds HTML to plain JavaScript objects. Declare what an element shows with an attribute and Bindary keeps it in step with your data. No virtual DOM and no build step: change tasks[2].status and one badge updates, however many tasks are on screen.

Data binding is the core, but Bindary is the whole client layer: routing with server-driven data loading, includes and components for reuse, form binding with type conversion and formatting.

Setting up

Bindary's modules load asynchronously, so configuration waits for componyx.bindary_modules.loaded. Once that resolves, set any properties and register your routes. Bindary launches on its own right after, so settings that affect how data is observed or routes are resolved are in place by then.

(async function ()
{
    await componyx.bindary_modules.loaded;
    $bindary.observing = true;
    $bindary.addRoute({ path: /^home$/, 
        viewURL: '/views/home.html', 
        controllerURL: '/js/controllers/home.js' });
})();

Keep that configuration synchronous. If you need to await something else first, or want to choose the moment yourself, for example after authentication or once Componyx.UI has finished rendering, set $bindary.launchOnLoad to false and call $bindary.launch() when ready. See the Bindary API reference for every setting.

Attributes

Bindary's HTML-side bindings are declared with attributes on the element itself. The short form uses the b- prefix, the strict form uses data-bindary-. Both are equivalent, so pick whichever suits your tooling and stay consistent

<span b-value="name"></span>
<span data-bindary-value="name"></span>

These docs use the short form throughout. The short form is active by default; switch with $bindary.useShorthand or configure a prefix of your own through $bindary.setCustomPrefix().

Where data lives

Bindary has three root data containers. They all hold a plain object; what differs is what that object is keyed by and therefore what shares it.

$bindary.appData is not keyed. One object for the whole page.
$bindary.routeData is keyed by route index, so every URL matching the same route definition shares it.
$bindary.viewData is keyed by route path, so each distinct URL holds its own.

For a dynamic route the difference matters. A route matching /product/123 and /product/456 is one route index and two route paths, so both pages share a routeData while each holds its own viewData.

How a key finds its container

A data-key without a container name is searched in order: viewData first, then routeData, then appData. The first container holding that root key wins, which means a key present in two containers silently resolves to the narrower one. Prefix the key with $ and name the container to be explicit.

<!-- searched viewData, then routeData, then appData -->
<span b-value="user.name"></span>

<!-- appData, no ambiguity -->
<span b-value="$.appData.user.name"></span>

Not every key resolves against a container. A context scopes part of the page to an object and inside that subtree keys resolve against the object first. Anything resolving against none of these falls back to window, which is how you point a context at an object you already hold globally. Such an object is not observed by default, but it can be, see below.

What survives a route change

routeData is retained when a route unloads and restored on return, which suits the state that belongs to a route rather than to one of its URLs: filters, sort order, a chosen tab. viewData is discarded, so each visit starts clean.

Both are configurable through $bindary.cacheRouteData and $bindary.cacheViewData. Setting $bindary.caching to false overrides both and discards everything, including cached views and controllers.

Loading data

A route can connect to the server and name the method to call and the response populates the containers before the view renders. Componyx ships backends for .NET and Node.js that handle the transport and the merge rules, so with one of those in place there is no fetch to write on the client: by the time your bindings are evaluated the data is already there.

$bindary.addRoute({
    path: /^products\/(\d+)$/,
    viewURL: '/views/product.html',
    controllerURL: '/scripts/product.js',
    dataConnect: true,
    dataRequest: { id: '$1' },
    dataServerLoad: 'Shop.Product.Controller.Load'
});

The response names the container it targets, so one call can fill viewData for this page and top up appData with something the whole application needs. It also carries rules describing how the incoming data is merged and later responses can arrive unprompted over the same connection to patch what is already there. See routes and backend for the server side.

Setting up data yourself

Without a server connection or for data that only exists in the browser, assign it yourself. That is also the route to take if you would rather fetch it your own way: the containers are plain objects, so anything that can produce one can fill them.

The route's controller is the natural place for it. A controller is a plain object of methods, named after the events they handle.

(function (ctrl)
{
    ctrl.load = () =>
    {
        $bindary.appData.demo = { intro: { count: 1 } };
    };

    ctrl.addCount = () => $bindary.appData.demo.intro.count++;

})($bindary.controller);

See controller for the full set of methods and their arguments.

Events

Every event can be handled in two places. The active route's controller handles it through a method of the same name and any code can subscribe globally through the matching event object. Both run, controller first.

ctrl.postRender = () => { };              // this route only
$bindary.onPostRender.add(function () { });   // every route

load and postLoad bracket a route: load after the route's data and sources are in, postLoad once the view has rendered. preRender and postRender bracket every render pass instead, so they run again on each update rather than only at route load. Reach for postRender when you need the DOM for something that can change after the first render and postLoad for one-time setup.

The data pipeline has its own pairs: preDataBind and postDataBind around input binding, preDataUpdate and postDataUpdate around incoming server data. Returning false from a pre-event cancels what follows, which is where validation and rejection belong.

Observing changes

Ordinary JavaScript is all you need. Set a property, push to an array, splice one out; the view updates for that change alone and nothing else re-renders.

// one new node, nothing else touched
$bindary.appData.colors.push({ name: "Teal" });

Changes are picked up through native Proxies and this is on by default. Set $bindary.observing to false before launch to turn it off, which leaves you registering changes manually as described below. Routes can override the setting individually through the route's own observing property, which applies to routeData and viewData.

Changes are coalesced, so a burst of mutations in the same tick produces a single render rather than one per assignment. To take that further and render on your own schedule, set $bindary.autoUpdateView to false and call $bindary.updateView() when you are ready. That setting governs observed changes only; data arriving from the server renders on its own path and is unaffected.

Observing your own objects

For an object outside the three containers, wrap it with $bindary.observe() and assign the result back. The second argument is the name Bindary will use to identify it.

window.myContainer = $bindary.observe({}, 'myContainer');

The object needs to be reachable by name for a context to point at it, which is why the example assigns to window.

The optional settings object can dispatch a CustomEvent on every change, which is how a native Web Component hears about its own data without polling. Cancel that event to reject the change and suppress the view update. The component attribute page shows this in use.

Registering changes manually

Changes to data Bindary cannot see and cases where you want to describe exactly which array indexes moved, are registered explicitly through $bindary.dataChange() and its variants. Updates can also be held back for a data-key or a whole container until you release them, which is what you want while a batch of server data is still arriving. See data changes.

Data-keys and context

A data-key is a dot-separated path into your data. Written in full it is unambiguous, but it is also repetitive, which is what b-context solves: it scopes a subtree to an object so the keys inside it become relative.

<!-- full key -->
<span b-value="account.user.name"></span>

<!-- scoped -->
<div b-context="account.user">
    <span b-value="name"></span>
</div>

Inside a repeat, each item becomes its own context automatically. Within a context, $parent reaches the level above, $value is the current item's value and $key its index or property name.

The separator is a dot by default and is readable from $bindary.dataKeySeparatorChar.

Expressions

Wrapping a data-key in {{ }} evaluates it as an expression rather than binding it directly. Expressions run in a sandboxed engine, not through eval and they resolve against the current context like any other key. They are the right tool for small presentational decisions; anything with real logic in it belongs in a controller function.

Example

<div b-context="demo.intro">
    <span b-value="count"></span> {{count === 1 ? 'item' : 'items'}}
    <a ui-type="Button" ui-text="Add" ui-primary="true"
        ui-has-icon="true" ui-css-class-icon="ico-plus"
        ui-command="$bindary.controller.addCount"></a>
</div>

$bindary.appData.demo.intro = { count: 1 };

ctrl.addCount = () => $bindary.appData.demo.intro.count++;

Result

Expressions also work as attribute values, which is how a Componyx.UI component property gets data-bound. Use b-attributes when the attribute needs a data-bound value mixed with literal text.

Components

A component is any object you register with $bindary.addComponent(). Bindary calls your initiator function when the element renders and uses whatever it returns as the context for that subtree, so a class, a custom element or a plain factory function all work.

Because each element gets its own instance and that instance is its own context, two components of the same type can sit on one page holding entirely different data. The markup inside them is identical; only the object behind it differs.

$bindary.addComponent('taskList', function (templateItem)
{
    return new TaskList(templateItem);
});

The component attribute pages use a standard Web Component, since that is what most people will reach for and show how to package one as a file so its markup, CSS and script load together on demand.