BG BGDatabase Home Setup How To Use Videos Example Breakdown Fields Export Import Data Binding Events Code Generation Addons

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 using string templates
  4. Use graph editor tool to describe calculation algorithm for graph binders as set of connected graph nodes

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/graph binders 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

Unit binders, injecting one single value to target component

# Name Description
1 BGDataBindingFieldGo Inject one single value from database to a component
2 BGDataBindingTemplateGo Inject value, derived from a text template from database to a component
3 BGDataBindingGraphGo The most advanced unit binder, which calculates the value to be injected using graph editor tool

Compound binders, injecting multiple values to multiple components at once

# Name Description
1 BGDataBindingBatchGo A compound binder (the same as several fields, templates and graph binders in one single binder)
2 BGDataBindingUiToolkitGo A compound binder (just like batch binder) for Unity UI Toolkit (can be downloaded here)
3 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 binder does.
4 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. Choose the type of the field to inject. The dropdown will contain all field types from your database
  3. Choose 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. Choose 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. Choose the target Component and field/property to inject a value to. The dropdown will contain all fields/properties from all attached Components, which have a 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 injects it again

How to use graph binder (BGDataBindingGraphGo)

  1. Attach BGDataBindingGraphGo component
  2. Select graph return type (bool, string, int, float, object)
  3. Choose the target Component and field/property to inject a value to. The dropdown will contain all fields/properties from all attached Components, which have a compatible type.
  4. Edit the graph using graph editor, use "Special/SetResult" node to pass a result
  5. Toggle "Live Update" on, if you want all field values to be monitored. If value of one of the field is changed, binder injects it again

How to use batch binder (BGDataBindingBatchGo)

  1. Attach BGDataBindingBatchGo component
  2. Drag GameObjects to either "Field Binders", "Template Binders" or "Graph Binders" table
  3. For field binders, choose 1) target component and field/property and 2) choose source Meta, Field and Entity
  4. For template binders, 1) choose target component and field/property and 2) fill in template (please read about template format below)
  5. For graph binders, 1) choose graph return type (bool, string, etc.) 2) choose target component and field/property and 3) edit calculation graph, using "Edit" button
  6. Important: if you plan to make a prefab out of the GameObject with attached batch binder, reference child GameObjects only.

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 choose 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. Choose 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

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 mobile OS (Android/IOS)

Our data binders use reflection to inject the value from the database to field/property

If you are targeting mobile OS (Android/IOS), you may encounter the situation, that field/property is stripped (removed) from the build. (read more information about code stripping here)

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 a 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 (UGUI-related)

  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