Data Binding

What is data binding?

With data binding you can:
  1. Inject value from database to any field of any component
  2. Monitor field(s) changes and inject value again if value is changed
  3. For string fields you can combine static text with multiple values from database

Why it could be useful?

The most obvious example- let say you want UI text component to show text like "Hit Points: [number of hit points]". With data binding you can assign this value with template and monitor it, so if [number of hit points] is changed in the database, the text field will also be updated. And with our localization addon, "Hit Points" string can be easily localized as well.

Binders overview

Name Description
BGDataBindingFieldGo Inject one single value from database to a component
BGDataBindingTemplateGo Inject value, derived from a text template from database to a component
BGDataBindingBatchGo The same as several fields and templates binders in one single binder
BGDataBindingRowGo This binder is used to inject multiple values from one single row. It uses the same naming convention to resolve fields/properties as BGDataBindingDatabaseGo
BGDataBindingDatabaseGo This binder is used for binder-less setup. One single binder is used to inject all values. It scans all components, which have BGDatabaseEntityId string field with assigned id and uses naming convention to inject the values (fields/properties must be named exactly as database fields and have the same type)

How to use single field binder (BGDataBindingFieldGo)

  1. Attach BGDataBindingFieldGo component
  2. Chose the type of the field to inject. The dropdown will contain all field types from your database
  3. Chose the target field/property to inject a value to. The dropdown will contain all fields/properties from all attached Components, which has the same type from step 2. So if you chose string type, this dropdown will contain all string fields and properties from all attached Unity's Components
  4. Chose the meta, entity and field to get the value from
  5. Toggle "Live Update" on, if you want the value to be monitored. If value is changed, binder inject it again

How to use template binder (BGDataBindingTemplateGo)

  1. Attach BGDataBindingTemplateGo component
  2. Chose the target field/property to inject a value to. The dropdown will contain all fields/properties from all attached Components, which has string type.
  3. Fill template text (please read about template format below)
  4. Toggle "Live Update" on, if you want all field values to be monitored. If value of one of the field is changed, binder inject it again

How to use batch field binder (BGDataBindingBatchGo)

  1. Attach BGDataBindingBatchGo component
  2. Drag GameObjects to either "Field Binders" or "Template Binders" table
  3. For field binders, chose 1)target component and field/property and 2) chose source Meta, Field and Entity
  4. For template binders, 1) chose target component and field/property and 2) fill in template (please read about template format below)
  5. Important: if you plan to make a prefab out of the GameObject with attached batch binder, do not reference any other GameObject, than its own children

How to use row binder (BGDataBindingRowGo)

  1. Attach BGDataBindingRowGo component
  2. Create your own script and name its fields exactly like database columns (case-sensitive). They also need to have exact types
  3. Attach you script to the same GameObject and chose it as a target component for data binding. (If your script was named exactly as table and added before BGDataBindingRowGo, it will be auto assigned as target component)
  4. Chose the source (table and entity)
  5. Toggle "Live Update" on, if you want all field values to be monitored. If value of one of the field is changed, binder inject it again

How to use database binder (BGDataBindingDatabaseGo)

  1. Attach BGDataBindingDatabaseGo component to any GameObject. [Important!] You need to have one single binder in your scene
  2. Create your own scripts and name their fields exactly like database columns (case-sensitive). They also need to have exact types
  3. Also add BGDatabaseEntityId string field to these components
  4. Attach any number of your scripts to any GameObjects and assign their BGDatabaseEntityId fields to valid row database ids. No need to attach any binder

Template format

We plan to replace templates with Node-based Graph tool. Check our Roadmap for more details

Template let you combine static text with multiple field values from database. Currently only one special tag is used, which allow to inject field value to text.
Use #FIELD(fieldID) to inject field value.
fieldID format is fieldName(or id)@entityId@metaName(or id) metaName(or id) is optional (but recommended)
So here are some of the template examples:

  1. Hit Points: #FIELD(hitpoints@47xVQlfHwUav9kozM7nIaw@Player)
  2. Hit Points: #FIELD(hitpoints@47xVQlfHwUav9kozM7nIaw)
  3. Hit Points: #FIELD(HDonu5dt1Ei/bCcUX2n93w@47xVQlfHwUav9kozM7nIaw)
  4. #FIELD(uiText@dw/e73Wm0U+faTMnh+POZQ@Ui): #FIELD(HDonu5dt1Ei/bCcUX2n93w@47xVQlfHwUav9kozM7nIaw)

Building for IOS

We are using Reflection to inject the value to field/property

If you are targeting IOS, you may encounter the situation, that property can be stripped (removed) from the build.

If you use only properties, marked as recommended (prefixed [RECOMMENDED]) (see full list below), you have nothing to worry about

However if you are using another properties, you want to force compiler to include them in the build.

There are couple of methods how to do it, the most straightforward is: to make direct references in the code.

Create a simple class, add private method, reference the properties you are using and add it to one of your scenes.

After that add link.xml to you project with following content

<linker>
       <assembly fullname="Assembly-CSharp.dll">
               <type fullname="PreventIosFromStripping" preserve="all"/>
       </assembly>
</linker>

More info about link.xml can be found here

Here is an example:

public class PreventIosFromStripping : MonoBehaviour
{
    private void Unused()
    {
        GetComponent<MyComponent>().myProperty1 = null;
        GetComponent<MyComponent>().myProperty2 = null;
        //etc.
    }
}

Full list of recommended properties

  1. SpriteRenderer.sprite
  2. Material.mainTexture
  3. MeshRenderer.sharedMaterial
  4. MeshRenderer.sharedMaterial.mainTexture
  5. Text.text
  6. TextMesh.text
  7. Image.sprite
  8. AudioSource.clip