Data Binding

Data Binding is how you get data from your game into the UI. Many of the properties of the various YUI Elements are bindable, and you can see which ones are bindable in the documentation page for each element. What does it mean to be bindable? Consider the following text element:

type: text
text: "100" // we want this to be the player health!

Wouldn't it be nice if we could replace the "100" with the actual health of our player object? Well, you can do that really easily:

type: text
text: @health // that's more like it!

By switching the value of text to @health instead of the literal string "100", that tells YUI to use the health variable on the current data context as the value for text. Assuming the current data context is the player object, then this text element will now display the health variable of the player.

This on its own is quite useful, but it gets really powerful when used with the panel's elements and template properties. For example:

type: panel
elements: @inventory_items
template:
  type: text
  text: @display_name

So what does this do? Well, the elements: @inventory_items tells the panel to data bind to the inventory_items field on our player object, and the template property tells it to render each item in the inventory_items array using a text element. And that text element is set to display the display_name variable on each item in that inventory_items array.

So ultimately, we're displaying the names of each item in the player's inventory! And that list will update automatically whenever you update the inventory_items list in your game code. That's pretty cool for 5 lines of YUI! Of course, the template doesn't need to be a simple text element. You can put any complex YUI element there instead to show as much information about each inventory item as you'd want.

One thing to note here, is that when using the panel like this, the data context for the template is changed to be the individual item from the array, to allow you to bind to the fields of that item. Otherwise, the binding would still apply to the top level data context, which would be much less useful.

So what's the Data Context exactly?

Simply put, the data context is the reference to the data from your game that you want to display in a screen, and so it acts as the default context for all data bindings in that screen. This will generally be a GameMaker object or struct, such as your player object. You set the data context for a Screen via the data_context variable on the associated yui_document object for that screen in the room. The general idea is that you can configure this data context per screen, and then as you update the various variables on the data context object/struct according to your game logic the UI will automatically update to display that information every frame, thanks to the data binding system. Set it and forget it!

As described in the panel example above, the data context for a panel's template will automatically change to match the each item. You can also manually change the data context for an element via the data_source shared property. This can be useful if your data context has variables which are themselves important structs or game objects.

Advanced Data Binding: YuiScript

So far the examples have only shown that you can bind to a single variable on the data context, but in fact there is a whole YuiScript scripting language that you can use when setting values on an element.

For example, what if we'd like our health text element to draw the text in red when the player's health is low?

type: text
text: @health
color: @health < 25 then red else white // then/else is equivalent to the ?: operator in GML

Yep, you can put an expression in there and YUI will evaluate that expression and use the result!

The YuiScript page covers all the many things you can do with data binding, so check it out once you've got the hang of the basics.