Data binding overview

Table of Contents

• Overview
• Syntax overview
• Virtual list
• Data binding events
• Custom data binding attributes

Data binding synchronizes the state of your UI with that of the game, effectively eliminating a lot of JavaScript boilerplate that would otherwise be needed.

Overview

The data binding system is a major part of Cohtml. It's main point is to eliminate the need to move as much as possible of the data to the UI so that the UI creators have full control over how it's displayed. Simultaneously, C++ engineers only need to write a couple of lines to expose all the data and move onto other tasks.

Data binding is a pretty popular feature in the web world and if you are familiar with angular.js or react.js this feature will be very familiar. Since it's written in C++ the system has better performance than all JavaScript libraries you can potentially use for the same purpose.

Cohtml allows for easy communication between your application and the UI via several mechanisms - one of them being data binding. See Communicating with the game for another one.

Using the model from the HTML

Once the object is exported from C++, it can be attached to the DOM using the set of data-bind-* properties. To complete the example from above, imagine that we want to move a nameplate in the UI using the player's left position:

<div class="nameplate" data-bind-style-left="{{g_TestPlayer.leftPos}}"></div>

Note the special double curly brace syntax ({{expression}}) that you need to use.

With the model exposed and the HTML using it, the <div> element is now linked to the player.

With these steps the <div> will automatically update anytime the model changes. Note that you didn't have to write any JavaScript to synchronize the UI and the game. Although this example is contrived, you can imagine how powerful this feature can become when dealing with a complex screen powered by tens of variables. Scroll below for more details on how to make use of the subsystem.

Note

Model's property of pointer type and value nullptr is not supported at the moment, i.e. expressions which are using it won't be updated.

Syntax overview

HTML/JavaScript syntax

The syntax of the data binding attributes is a JavaScript expression. The simplest expressions only refer to the model's properties and are encapsulated in double curly braces like we just saw above:

<div data-bind-style-left="{{myModel.leftPos}}"></div>

where myModel is a named model which has a leftPos property.

You can also construct complex expressions such as:

<div data-bind-style-left="{{myModel.LeftPos}}.toFixed()"></div>
<div data-bind-style-left="Math.pow({{myModel.LeftPos}}, 2)"></div>

Only the code referring to the model's properties needs to be inside the curly braces.

Note

Expressions referring to a single model property are the fastest performance-wise since the bound value is directly assigned within the SDK. Complex expressions require JavaScript evaluation and are more expensive than single value bindings.

Warning

: DOM standard doesn't define order in which attributes must be evaluated, so evaluation of each expression must be independent from the evaluation order. A good practice is to avoid any assignment operations in your data bind expression.

Supported data-bind-* attributes

data-bind-value

The data-bind-value attribute takes a value and assigns the node's textContent property to it.

Example:

<span data-bind-value="{{player.health}}"></span>

If you want to round the value then you can use the toFixed method.

Example:

<span data-bind-value="{{player.health}}.toFixed(2)"></span>

data-bind-html

The data-bind-html attribute takes a value and assigns the node's innerHTML property to it. This allows to create text elements that can have formatting and embedded images.

Warning

: data-bind-html should be used to create small pieces of DOM without more data-binding attributes inside.

Example:

<span data-bind-html="{{item.toolip}}"></span>

Styling attributes

The following attributes allow you to modify the element's style:

Data bind attribute	Affected style property	Accepted values
data-bind-style-left	left	string or number (px)
data-bind-style-top	top	string or number (px)
data-bind-style-opacity	opacity	floating point number between 0 and 1
data-bind-style-width	width	string or number (px)
data-bind-style-height	height	string or number (px)
data-bind-style-color	color	CSS color as string or unsigned RGBA
data-bind-style-background-color	background-color	CSS color as string or unsigned RGBA
data-bind-style-background-image-url	background-image	URL to the image
data-bind-style-transform2d	transform	string, containing 6 comma-separated numbers
data-bind-style-transform-rotate	transform: rotate(..)	string or number (deg)

All the properties above that take number (px) will assume that the number is a measurement in pixels (e.g. binding 42 to data-bind-style-left will be equivalent to left: 42px).

(Unsigned RGBA) have the same semantics as hexadecimal syntax where 1th byte is alpha, 2th is blue, 3th is green and 4th is red.

If data-bind-style-transform-rotate takes a number (deg) then it will assume that the number is a measurement in degrees (e.g. binding 90.5 to data-bind-style-transform-rotate will be equivalent to transform: rotate(90.5deg)).

There are two other styling attributes - data-bind-class and data-bind-class-toggle. data-bind-class takes a string in the format data-bind-class="class-name[;class-name]". The class name can be any CSS class. The class specified by class-name will be added to the element. Here's a brief example:

<head>
<style>
    .class-type-left-10 {
        left : 10px;
    }
    .class-type-left-20 {
        left : 20px;
    }

    .class-type-top-30 {
        top : 30px;
    }
    .class-type-top-40 {
        top : 40px;
    }
</style>
</head>
<body>
    <div data-bind-class="'class-type-'+{{this.type_1}};'class-type-'+{{this.type_2}}"></div>
</body>

data-bind-class-toggle takes a string in the format data-bind-class-toggle="class-name:bool_condition[;class-name:bool_condition]". The class-name is the name of some CSS class and bool_condition is a boolean or an expression that evaluates to a boolean. If the boolean is true or the condition evaluates to true, the class specified by class-name is added to the element, otherwise it is removed.

Let's see an example with class toggling:

<head>
    <style>
    .red {
        background-color: red;
    }
    </style>
</head>
<body>
    <div class="ToggleWithExpression" data-bind-class-toggle="red:{{this.Health}} < 50">Something red</div>
    <div class="ToggleWithBoolean" data-bind-class-toggle="red:{{this.hasLowHealth}}">Something red</div>

The red class will be present on ToggleWithExpression as long as {{this.Health}} < 50 is true, changing the element's background to red. Respectively the red class will be present on ToggleWithBoolean as long as {{this.hasLowHealth}} is true. Otherwise it won't be applied and the element will have whatever background it usually has.

Note

The faster way is using directly boolean instead of expression which would be evaluated to boolean.

Structural data binding

The attributes above only allow you to modify the visual style and the text content of DOM elements. The real power of the data binding system stems from the fact that you can also modify the entire DOM tree with it. This is done via two other attributes:

• data-bind-if: Displays a DOM element based on a condition. The expressions in the attribute value should evaluate to a boolean value.
• data-bind-for: Repeats a DOM node for each element in a collection. The basic syntax is data-bind-for="iter:{{myModel.arrayProperty}}", where myModel.arrayProperty must be an array, and iter is a variable used for iteration, which is available in data binding attributes for the child DOM nodes. The syntax for accessing properties of an iterator in a data-bind-for is {{iter.property}}.

You can also use the full form data-bind-for="index, iter:{{myModel.arrayProperty}}", where index is loop counter. If you don't need use the index or iterator you can use _ e.g. data-bind-for="index, _:{{myModel.arrayProperty}}"

If the data-bind-for collection is a std::vector then the elements could be also raw/std::shared_ptr/std::unique_ptr pointers (or your custom pointer type).

Warning

• data-bind-for with a collection of primitive types is not supported.
• Changes via JS to DOM element with data-bind-if attribute will be lost if the expression's value is switching between true and false.
• Changes via JS to DOM element generated from data-bind-for will cause undefined behavior if the collection's size is changed.

Structural data binding allows you to generate entire screens by just providing a template for each element in a collection (e.g. all items in the player's inventory) and the system will take of repeating the template as many times as necessary.

The next several examples only show the relevant HTML because the C++ model is straightforward:

< !-- displays a warning message if the player's health is low -->
<div data-bind-if="{{g_Player.health}} < 40" id="playerHPLowWarn">
    Player needs a medic!
</div>

< !-- The following will result into a list, depending on the weapons the player has, like so:
    Rare Gun
    Common Sword
    Rare Dagger
-->
<div data-bind-for="weapon:{{player.weapons}}">
    <span data-bind-if="{{weapon.isRare}}">
        Rare
    </span>
    <span data-bind-if="!{{weapon.isRare}}">
        Common
    </span>
    <span data-bind-value="{{weapon.name}}">
</div>

< !-- Enumerates all pets of the player -->
<div class="petsList">
    <div data-bind-for="iter:{{g_Player.pets}}" class="petItem">
        <div class="petName" data-bind-value="{{iter.name}}"></div>
        <div class="petSpeed" data-bind-value="{{iter.info.speed}}"></div>
        <div class="petType" data-bind-value="{{iter.info.isMount}} ? 'Mount' : 'Companion'"></div>
    <div>
</div>

< !-- Will result in -->
<div class="petsList">
    <div class="petItem">
        <div class="petName">Sabertooth tiger</div>
        <div class="petSpeed">80</div>
        <div class="petType">Mount</div>
    </div>
    <div class="petItem">
        <div class="petName">Eagle</div>
        <div class="petSpeed">90</div>
        <div class="petType">Companion</div>
    </div>
    <div class="petItem">
        <div class="petName">Pony</div>
        <div class="petSpeed">70</div>
        <div class="petType">Mount</div>
    </div>
</div>

< !-- Access loop counter -->
<div class="petsList">
    <div data-bind-for="index, iter:{{g_Player.pets}}" class="petItem">
        <div data-bind-class="'petName' + {{index}}" data-bind-value="{{iter.name}}"></div>
    <div>
</div>

< !-- Will result in -->
<div class="petsList">
    <div class="petItem">
        <div class="petName0">Sabertooth tiger</div>
    </div>
    <div class="petItem">
        <div class="petName1">Eagle</div>
    </div>
    <div class="petItem">
        <div class="petName2">Pony</div>
    </div>
</div>

Virtual list

In case you need pagination, you can use the method engine.createVirtualList which will create a view like object with the following properties:

• startIndex - index from which the data-bind-for will start generating DOM elements. The default value is 0.
• pageSize - maximum number of elements that will be generated from the data-bind-for.

Virtual lists are used by applying them to the data-bind-for attributes with an array of your model. The virtual list will serve as a view, so it will not change the array. One virtual list can be used in different expressions with different arrays and if you change a property of the virtual list it will automatically apply the change to all arrays that it is associated with. The only thing that you must do is to call synchronizeModels.

For example, let's say we have a model g_Game with property heroes which is an array and has ~100 elements. At any time we want to show only 5 heroes and want buttons which will show the next and previous page. It will be way more efficient if we generate only 5 UI elements, instead of generating a 100 and hiding 95 of them. This can be achieved easily with only a few lines of JavaScript.

<div class="heroes-board">
    <div class="hero" data-bind-for="iter:uiState.vList({{g_Game.heroes}})">
        ...
    <div>
    <div class="button" onclick="nextPage()"> </div>
    <div class="button" onclick="prevPage()"> </div>
</div>

<script>
    var uiState = new Object;

    function update() {
        engine.synchronizeModels();
        window.requestAnimationFrame(update);
    }

    engine.on("Ready", function() {
        uiState.vList = engine.createVirtualList();
        uiState.vList.startIndex = 0;
        uiState.vList.pageSize = 5;
        windows.requestanimationframe(update);
    }

    function nextPage() {
        if (uiState.vList.startIndex + uiState.vList.pageSize < g_Game.heroes.length)
            uiState.vList.startIndex += uiState.vList.pageSize;
    }
    function prevPage() {
        if (uiState.vList.startIndex - uiState.vList.pageSize >= 0)
            uiState.vList.startIndex -= uiState.vList.pageSize;
    }
</script>

Data binding events

The data binding events are dom element attributes for attaching event listeners on the DOM.

Example:

<div class="shop-menu" data-bind-for="item:{{g_Shop.items}}">
    <div class="item-box" data-bind-[eventName]="g_Shop.buyItem(event, this, {{item}})">
    </div>
</div>

• event - The JavaScript Event object from the fired event.
• [eventName]- All events listed in Supported Events. Example: click, mouseup, dblckick, etc.
• this - Is set to the DOM element on which the handler is registered.

Supported Events

• abort: is fired when the loading of a resource has been aborted.
• blur: is fired when an element has lost focus
• click: is fired when a pointing device button (usually a mouse's primary button) is pressed and released on a single element.
• dblclick: is fired when a pointing device button (usually a mouse's primary button) is clicked twice on a single element.
• error: is fired when an error occurred; the exact circumstances vary, events by this name are used from a variety of APIs.
• focus: is fired when an element has received focus.
• focusin: is fired when an element is about to receive focus.
• focusout: is fired when an element is about to lose focus.
• keydown: is fired when a key is pressed down.
• keypress: is fired when a key that produces a character value is pressed down.
• keyup: is fired when a key is released.
• load: is fired when progression has begun successful.
• mousedown: is fired when a pointing device button is pressed on an element.
• mouseover: is fired when a pointing device is moved onto the element that has the listener attached or onto one of its children.
• mouseout: is fired when a pointing device (usually a mouse) is moved off the element that has the listener attached or off one of its children.
• mouseenter: is fired when a pointing device (usually a mouse) is moved over the element that has the listener attached.
• mouseleave: is fired when the pointer of a pointing device (usually a mouse) is moved out of an element that has the listener attached to it.
• mousemove: is fired when a pointing device (usually a mouse) is moved while over an element.
• mouseup: is fired when a pointing device button is released over an element.
• input: is fired synchronously when the value of an <input>, <select>, or <textarea> element is changed.
• change: is fired synchronously when the value of an <input>, <select>, or <textarea> element is changed and committed.
• scroll: is fired when the document view or an element has been scrolled.
• touchstart: is fired when one or more touch points are placed on the touch surface.
• touchend: is fired when one or more touch points are removed from the touch surface.
• resize: is fired when the document view has been resized.
• durationchange: is fired when the duration attribute has been updated.
• emptied: is fired when the media has become empty.
• ended: is fired when playback or streaming has stopped because the end of the media was reached or because no further data is available.
• seeked: is fired when a seek operation completed.
• seeking: is fired when a seek operation began.
• timeupdate: is fired when the time indicated by the currentTime attribute has been updated.
• wheel: is fired when a pointing device (usually a mouse) wheel button is rotated.

Custom data binding attributes

In some cases default data binding attributes are not powerful enough to satisfy the needs of our users. In these cases you can create your own attributes.

To register a custom attribute use engine.registerBindingAttribute("my-attribute-name", MyAttributeHandler).

class MyAttributeHandler {

    init(element, value) {
    /// This will be executed only once per element when the attribute attached to it is bound with a model.
    /// Set up any initial state, event handlers, etc. here.
    }

    deinit(element) {
    /// This will be executed only once per element when the element is detached from the DOM.
    /// Clean up state, event handlers, etc. here.
    }

    update(element, value) {
    /// This will be executed everytime that the model which the attribute is attached to is synchronized.
    }
}

engine.on('Ready', function () {
    engine.registerBindingAttribute("my-attribute-name", MyAttributeHandler);
}

• element - The DOM element to which the handler is attached
• value - The result from the evaluation of the attribute's expression in the HTML

...and then you can use it on any number of DOM elements:

<div data-bind-my-attribute-name="{{dataBindingExpression}}"> </div>

Creating the attribute handlers

Once you call registerBindingAttribute a new handler will be created for each element in DOM which has the data-bind-my-attribute-name attribute.

Note

init and the first update will be executed on the first synchronizeModels after an attribute handler is registered.

init and deinit are useful to manage the lifetime of the attribute. In the case where the element with a custom attribute is generated via data-bind-if and data-bind-for these callbacks will be called when the element is attached to or removed from the DOM.

All of the callbacks are optional and can be skipped.

It's not possible to override the behavior of existing data bind attributes. To prevent feature name collisions, it is a good practice to add a prefix to all new custom attribute names.

The following example illustrates how to create your own equivalent of data-bind-value which capitalizes the provided value.

<div data-bind-coh-capitalize="{{g_Game.text}}"></div>

<script src="cohtml.js"> </script>
<script>
    class Capitalize {
        update(element, value) {
            element.textContent = value.toUpperCase();
        }
    }

    engine.on('Ready', function () {
        engine.registerBindingAttribute("coh-capitalize", Capitalize);
        engine.createJSModel("g_Game", {
            text: "lorem ipsum",
        });
        engine.synchronizeModels();
    });
</script>

The following example illustrates how to create custom event handlers.

<div data-bind-coh-events="{{g_Game.state}}"></div>

<script src="cohtml.js"> </script>
<script>
    class MyCustomEventFamily {
        constructor() {
            this.state = null;
        }

        init(element, value) {
            this.state = value;

            this.event1 = element.addEventListener("eventName1", (event) => {
                eventHandler1(event, this.state);
            });

            this.event2 = element.addEventListener("eventName2", (event) => {
                eventHandler2(event, this.state);
            });
        }

        update(element, value) {
            this.state = value;
        }

        deinit(element) {
            element.removeEventListener(this.event1);
            element.removeEventListener(this.event2);
        }
    }

    engine.on('Ready', function () {
        engine.registerBindingAttribute("coh-events", MyCustomEventFamily);
        engine.createJSModel("g_Game", {
            state : 1
        });
        engine.synchronizeModels();
    });
</script>

Observable models

Observable model is a smart object which will automatically push itself for update when some of his properties is changed.

This is useful in cases were you need to keep active state. Some very common scenarios are character selection screens, quest logs, inventories, shops etc. In these case observable models:

• Eliminates the need to track indexes of selected elements
• Improve readability of data bind attributes.
• In the most cases improve the performance, because data bind attribute expressions are simpler.

You can create observable model with ‘engine.createObservableModel('modelName’)`

Example:

Without observables

<div id="target" data-bind-value="{{gameState.players}}[{{gameState.selected}}].money + '$'"></div>
<script src="cohtml.js"> </script>
<script>

    engine.on('Ready', function () {
        let gameState = {
            players: [ {money: 100}, {money: 200}, {name: 300} ],
            selected: 0
        }
        engine.updateWholeModel(gameState);
        engine.synchronizeModels();

        gameState.selected = 1;
        engine.updateWholeModel(gameState);
        engine.synchronizeModels();
    });
</script>

With observable

<div id="target" data-bind-value="{{activeState.selectedPlayer.money}} + '$'"></div>
<script src="cohtml.js"> </script>
<script>

    engine.on('Ready', function () {
        let gameState = {
            players: [ {money: 100}, {money: 200}, {name: 300}],
        }
        engine.createObservableModel("activeState");

        // Will call engine.updateWholeModel(activeState) for us
        activeState.selectedPlayer = gameState.players[0];
        // Will update the target element
        engine.synchronizeModels();

        activeState.selectedPlayer = gameState.players[1];
        engine.synchronizeModels();
    });
</script>

Note

Observable models will not track properties of their properties. For example this activeState.selectedPlayer.money = 100 will not cause auto update.

As you can see, this gives a convenient way to update the active state without extra work. The example above has one big down side. If the game update 'gameState' this will not automatically push 'activeState' for update, because the 'gameState' don't know about existing of 'activeState'. This will lead to desynchronization between game and UI. We can solve this problem with use of engine.addSynchronizationDependency(gameState, activeState). This method will create one way dependency between 'gameState' and 'activeState', which means that each time when 'gameState' is pushed for update, 'activeState' will be push too.

Example:

<div id="target" data-bind-value="{{activeState.selectedPlayer.money}} + '$'"></div>

<script src="cohtml.js"> </script>
<script>

    engine.on('Ready', function () {
        let gameState = {
            players: [ {money: 100}, {money: 200}, {name: 300} ],
        }
        engine.createObservableModel("activeState");
        engine.addSynchronizationDependency(gameState, activeState);

        // Will call engine.updateWholeModel(activeState) for us
        activeState.selectedPlayer = gameState.players[1];
        // Will update the target element
        engine.synchronizeModels();

        gameState.players[1].money = 50;

        // Will push 'activeState' for update too
        engine.updateWholeModel(gameState);
        engine.synchronizeModels();
    });
</script>

Now we can update our 'gameState' independently from 'activeState' and everything will work as we expected.

In cases where you don't need dependency between 2 models anymore you can use engine.removeSynchronizationDependency(gameState, activeState) to remove it.

You can find more detailed sample of the observable models in Samples/uiresources/ObservableModels