To introduce data binding, let’s take a relatively simple scenario. Suppose you want to create a relationship between an input box (the source element) and another input box (a bound element) where changes made to the source are automatically reflected in the bound element and vice versa. This type of relationship is referred to as "two-way data binding" and is depicted in the following images:

As the user changes the source element, the bound element is automatically updated.

As the user changes the bound element, the source element is automatically updated.

To program this type of functionality, you must first create the source element and then create the bound element with two-way binding, as shown in the following code:

<?xml version="1.0" encoding="utf-8" ?>
<?import href="box://ocpToolkit/theme/default/toolkit.box"?>
<?import href="box://ocpToolkit/content/core/coreGadgets.box"?>

<window xmlns="http://www.aol.com/boxely/box.xsd"
  xmlns:s="http://www.aol.com/boxely/style.xsd"
  xmlns:on="http://www.aol.com/boxely/reaction.xsd"
  s:minHeight="125"
  s:minWidth="475"
  s:maxHeight="125"
  s:maxWidth="475"
  title="Two-Way Data Binding"
  s:fill="white">

  <vbox>
    <hbox flex="1" s:height="10" />

    <label value="Two-way Data Binding"  s:fontBold="true" />
    <hbox flex="1" s:height="10" />
    <hbox>
      <label value="Source Element:" />
       <!-- Source element -->
      <input id="sourceData" value="Some Value"  s:width="360" />
    </hbox>
    <hbox flex="1" s:height="10" />
    <hbox>
      <label value="Bound Element:" s:fontFamily="Arial" />
       <!-- Bound element with two-way data binding -->
      <input value="" s:width="360" >
        <binding elementSource="sourceData" targetProperty="value" path="value"
          method="twoWay" />
      </input>
    </hbox>

  </vbox>

</window>

In the above code, the source element is an input gadget with the "sourceData" id.

The bound element is also an input gadget; it contains the child binding element, which binds the parent to the source identified in the elementSource attribute. The targetProperty attribute indicates which property of the bound element should be updated when a change occurs, and the path attribute indicates the property of the source element to use in the update. The method attribute indicates whether the binding is one-way or two-way. With two-way binding, changes made to the source are reflected in bound boxes, and changes made to a bound box are reflected in the source.

The Boxely UI Toolkit also supports one-way binding, where changes made to the source are reflected in bound boxes, but changes made to a bound box are not reflected in the source, as shown in the following images:

As the user changes the source element, the bound element is automatically updated.

As the user changes the bound element, the source element remains is unaffected.

The following code demonstrates how to do this:

<?xml version="1.0" encoding="utf-8" ?>
<?import href="box://ocpToolkit/content/core/coreGadgets.box"?>
<?import href="box://ocpToolkit/theme/default/toolkit.box"?>

<window xmlns="http://www.aol.com/boxely/box.xsd"
  xmlns:s="http://www.aol.com/boxely/style.xsd"
  xmlns:on="http://www.aol.com/boxely/reaction.xsd"
  s:minHeight="125"
  s:minWidth="475"
  s:maxHeight="125"
  s:maxWidth="475"
  title="One-Way Data Binding"
  s:fill="white">

  <vbox>
    <hbox flex="1" s:height="10" />
    <label value="One-way Data Binding"  s:fontBold="true" />
    <hbox flex="1" s:height="10" />
    <hbox>
      <label value="Source Element:" />
       <!-- Source element -->
      <input id="sourceData" value="Some Value"  s:width="350" />
    </hbox>
    <hbox flex="1" s:height="10" />
    <hbox>
      <label value="Bound Element:" s:fontFamily="Arial" />
       <!-- Bound element with one-way data binding -->
      <input value="" s:width="350" >
        <binding elementSource="sourceData" targetProperty="value" path="value" 
          method="oneWay" />
      </input>
    </hbox>
  </vbox>
</window>

In the above code, notice that the binding element’s method attribute is set to "oneWay" indicating a directional relationship.

The Boxely UI Toolkit also supports collection binding, where you can bind a template (defined in a .box file) to an array of elements (defined in a JavaScript file). For example, you might use collection binding to populate a list of items in a scene, as shown in the following image.

When the user clicks "Bind To Collection", the list of email items populates.

To implement this scenario, you must first create the element that will store the list in your .box file. Then, within that element, you must specify the binding rules that will bind the source data to each item in the list.

<?xml version="1.0" encoding="UTF-8"?>
<?import href="../../../../ocpSamples/theme/samples.box"?>

<window xmlns="http://www.aol.com/boxely/box.xsd"
    xmlns:s="http://www.aol.com/boxely/style.xsd"
    xmlns:on="http://www.aol.com/boxely/reaction.xsd" chromeless="true"
    id="window" translucent="false" s:height="470" s:width="650" 
    s:mainWidth="500"  title="Databound List Population" resizable="true">

    <code id="main" language="jscript" src="DataBoundListSample.js"/>

  <vbox style="bordered">
    <hbox s:vAlign="center" s:hAlign="center"> 
      <button label="Bind To Collection" on:click="onBind();"/>
    </hbox>
  </vbox>

  <listBox id="listBox" s:flex="1" selectMode="multiple">
    <columns header="true">
      <column id="column1" name="From" s:minWidth="250"/>
      <column id="column2" name="To" s:minWidth="250"/>
      <column id="column3" name="Subject" s:flex="1"/>
    </columns>
    <rows id="myRows">
      <binding collectionSource="EMailItems" method="oneWay" replication="full">
        <template>
          <listItem style="rowContainer">
            <label s:fontFamily="Arial" value="{from}" />
            <label s:fontFamily="Arial" value="{to}" />
            <label s:fontFamily="Arial" value="{subject}" s:flex="1"/>
          </listItem>
        </template>
      </binding>
    </rows>
  </listBox>

</window>

In the above code, the bound element is a list of email items. Each item includes a "From", "To", and "Subject" field. At runtime, these items will display in an listBox containing three columns and an undefined number of rows. Within the rows element, the binding element connects the rows to the source object (in our case, a collection named "EmailItems"). The template element contained within the binding element associates data in the source object with the appropriate row container.

Once you’ve defined the bound element in the .box file that describes your scene, you can create the JavaScript code that describes the source element:

function myEmailItem()
{
  this.from = "";
  this.to = "";
  this.subject = "";
}

function onBind()
{
  var collection = null;
  collection = shell.serviceManager.basics.array;

  var emailItem1 = new myEmailItem();
  emailItem1.from = "lovemonster@cupid.com";
  emailItem1.to = "marco@polo.com";
  emailItem1.subject = "Let’s meet!";
  collection.addValue(emailItem1);

  var emailItem2 = new myEmailItem();
  emailItem2.from = "imaginaryfriend@bouncebackemails.com";
  emailItem2.to = "marco@polo.com";
  emailItem2.subject = "Long time no speak...";
  collection.addValue(emailItem2);

  var emailItem3 = new myEmailItem();
  emailItem3.from = "one@dummydomain.com";
  emailItem3.to = "marco@polo.com";
  emailItem3.subject = "1 2 3";
  collection.addValue(emailItem3);
      
  scene.EMailItems = collection;
}

In the above code, the myEmailItem function defines the JavaScript object that represents an item in the collection. In the onBind function, we instantiate the myEmailItem object three times, adding it to our collection object (a basics.array). As our last step, we set a DOM object in the scene equal to the our collection object (the basics.array), which binds the data to the specified scene element.

Now that you’ve been introduced to data binding and collection binding, let’s try it out in the "To-Do List" application. Proceed to the next section, "To-Do List" Exercise 9.1: Using data binding.

In this exercise, you will create a data source object that represents a "to-do" note and bind the elements of the noteArea gadget to this object. All changes made to the data source object will be automatically reflected in bound boxes.

To complete the exercise, follow these steps:

Step 1: Create a new data source object named NoteItem

To get started, you must first define a data source object that represents a "to-do" note, as well as the functions needed to manage data within the object.

To do so, create a new JavaScript file named NoteItem.js and add code to:

You can create these functions on your own. Or, to save time, you can use the NoteItem.js exercise file, which is located in the ToDoList/common directory.

The contents of the NoteItem.js file are shown here:

function NoteItem() {}

NoteItem.prototype.title = "";
NoteItem.prototype.date = "";
NoteItem.prototype.image = "";
NoteItem.prototype.description = "";
NoteItem.prototype.listeners = [];

NoteItem.prototype.setTitle = function (title)
{
  this.title = title;
  this.notifyPropertyChange("title");
}

NoteItem.prototype.setDate = function (date)
{
  this.date = date;
  this.notifyPropertyChange("date");
}

NoteItem.prototype.setImage = function (image)
{
  this.image = image;
  this.notifyPropertyChange("image");
}

NoteItem.prototype.setDescription = function (description)
{
  this.description = description;
  this.notifyPropertyChange("description");
}


NoteItem.prototype.addObjectListener = function (object)
{
  this.listeners.push(object);
}

NoteItem.prototype.implementsProtocol = function (protocol)
{
    return (protocol == "EEObjectSource");
}

NoteItem.prototype.removeObjectListener = function (object)
{
  for (i = 0; i < this.listeners.length; i++)
  {
    if (this.listeners[i] == object)
    {
      this.listeners[i] = null;
      this.listeners.splice(i, 1);
      break;
    }
  }
}

NoteItem.prototype.notifyPropertyChange = function (property) 
{
  if (this.listeners != null)
  {
    for (i = 0; i < this.listeners.length; i++)
    {
      if (this.listeners[i] != null)
      {
        this.listeners[i].onPropertyChanged(this, property);
      }
    }
  }
}

Step 2: Instantiate the NoteItem object and add it to the DOM of the scene

Next, in the noteArea gadget’s onInitialized function, you must instantiate the NoteItem object and then use the addDOMObject method to add the NoteItem object to the DOM of the scene. (By adding the NoteItem object to the DOM of the scene, it is made available to all JavaScript and .box files that make up the application.)

Open the noteAreaGadgets.js file and add the code shown below in bold to complete this step:

component.prototype.onInitialized = function()
{ 
  this.todoItem = new NoteItem();
  this.scene.addDOMObject("todoItem", this.todoItem);
}

Step 3: Change the code that modifies noteArea parts to use the data source object

Now that you’ve created the data source object and instantiated it in the application, you need to change the JavaScript functions that manipulate the "to-do" item data to use the data object’s methods.

Step 4: Bind the parts of the noteArea gadget to the data source object

To bind the parts of the noteArea gadget to the NoteItem data source object, use this procedure:

Step 5: Testing your application

Now when you run your application, the "to-do" list items that you create and view are bound to the NoteItem data source object. When the data source object is modified, the changes will automatically be reflected in the noteArea gadget.

In this chapter, you learned how to use data binding to create a relationship between a Boxely scene element and a data source. Data binding makes it easy to author data-driven windows, minimizing the scripting needed to manipulate information.