1.3.0.2
Prysm
Data binding overview

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.

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.
Warning
Data binding attributes are taken into account only for static DOM nodes - i.e. HTML nodes that were present in the mark-up during the parsing of the document. It will not work with dynamically created nodes added to the DOM with JavaScript.

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.

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.
  • 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>