Data Binding

Overview #

The data binding feature is a major part of Gameface. Its main point is to automatically expose C# data to the UI and allow the UI creators to have full control over how it’s displayed. Effectively, it eliminates a lot of JavaScript boilerplate by automatically synchronizing your C# data with your JavaScript front-end.

How to use #

As with any other powerful feature, data binding requires a few steps to set up. To illustrate how this works let’s look at the following general steps based on a Unity3D’s MonoBehavior class:

1. Define your C# object with members and register it as a data model.
2. Update the members of your data model and synchronize it with the UI.
3. In your HTML elements, use the data-binding qualifiers to signal that they should automatically be synchronized to the objects in your application.

using cohtml;
using cohtml.Net;
using UnityEngine;

// Marked with this attribute to register that class as a data-bind model
[CoherentType]
public class Player
{
	// Expose the fields and properties to JavaScript with this attribute
	[CoherentProperty("name")]
	public string Name = "Default Player Name";
}

public class MyDataBindingClass : MonoBehaviour
{
	// Creating an object of your custom class.
	private Player playerModel = new Player();

	// The CohtmlView with your UI.
	private CohtmlView viewComponent;

	private void Start()
	{
		viewComponent = GetComponent<CohtmlView>();

		// You can only register your model after the View is sufficiently initialised
		viewComponent.Listener.ReadyForBindings += () =>
		{
			// This exposes your model to the front-end with the given name (i.e. "Player")
			ModelData createdModel = viewComponent.NativeView.CreateModel("Player", playerModel);

			if (createdModel != null)
			{
				playerModel.Name = "New Player Name";

				// Mark your model as an object that has changed.
				viewComponent.NativeView.UpdateWholeModel(playerModel);
				// Synchronize the data between backend/frontend for all marked models.
				viewComponent.NativeView.SynchronizeModels();
			}
		};
	}
}

// And finally in the HTML page, you can display your data-model members in the following way
<div data-bind-value"{{Player.name}}"> </div>

Following this generic setup, the value of Player.name will be automatically appended to the <div> element in your HTML page as soon as you synchronize the C# data with the UI.

Step by step guide #

Now that you’ve seen a short overview of how to implement the Data Binding feature, lets break down the process into smaller steps and go into more detail of how everything works.

Step 1 - Defining your data model object #

You need to tell Gameface what game objects you’d like to expose. Any such exposed object we call a data model. In order to register an object as a data model, you first have to declare your class and the fields/properties you want to expose. It is important to mark your class with the cohtml.Net.CoherentType attribute and your fields/properties with the cohtml.Net.CoherentProperty attribute. Note that you can provide a string parameter to the CoherentProperty attribute which will be the alias of your field in the JavaScript.

[CoherentType]
public class Player
{
	[CoherentProperty("name")]
	public string Name;
}

Step 2 - Registering your object as a data model #

The next step is to utilize the CohtmlView.NativeView.CreateModel API to notify the SDK that you want to create a data model with a specific name (this will be the alias of your data model which you can use to access it in JavaScript). It is important to perform this step during (or after) the CohtmlView.Listener.ReadyForBindings delegate, which notifies you when the CohtmlView.NativeView object is ready to create new data models.

viewComponent.Listener.ReadyForBindings += () =>
{
	viewComponent.NativeView.CreateModel("Player", playerModel);
};

Step 3 - Notifying the SDK that a data model needs to be updated #

Next, when a property in your model has changed (e.g. some game data), you need to tell Gameface that the data model needs to be updated in the UI. To achieve this, you have to utilize the CohtmlView.NativeView.UpdateWholeModel API:

CohtmlView.NativeView.UpdateWholeModel(playerModel);

Step 4 - Synchronizing game data with your UI #

Calling the UpdateWholeModel API from the previous step does not actually update the UI - rather, it only marks it internally as “dirty” so the SDK knows that the data model needs to be synchronized with the UI. To avoid constant UI updates, you can utilize the CohtmlView.NativeView.SynchronizeModels API that walks through all “dirty” data models and synchronizes them with the UI and the game.

CohtmlView.NativeView.SynchronizeModels();

Step 5 - Displaying the C# data in the UI #

Once we’ve performed the C# side steps, its time to display our data in the UI. This can be achieved by simply making use of the data-bind-value attribute which takes a property of your data model and appends in to the content of an HTML element.

<div data-bind-value"{{Player.name}}"> </div>

To find out more information about using the Data Binding feature on the frontend side and what other data-bind attributes it offers, please refer to the corresponding content creation docs from our native documentation.

Step 6 (Optional) - Unregistering a data model #

Generally, upon closing, reloading a View, or navigating to a new URL, Cohtml will automatically unregister and remove all registered models, events and call handlers.

You can unregister models from binding using the CohtmlView.NativeView.UnregisterModel API. This removes the model by instance pointer. Unregistering will not remove any elements bound to the model - they will preserve their last state.

Supported C# types #

Currently, the objects you want to register as data models must be C# classes. Inside your objects you can have fields or properties of primitive C# types (numbers, string and bool) and collections such as Array and List.

Planned future support #

In the upcoming releases of Gameface, we’ve plans to consider introducing support for:

• Dictionary collections
• Exposing C# methods of your data models
• structs, enums and other Unity3D/C# common types such as Transform, Vector3, Color, etc.