Data Binding

Certain times it can be very useful to bind information to a Control. Controls such as ListView, ComboBox, Paginator, to name a few, benefit greatly from the Data Binding concept.

To demonstrate the capaibility of Data Binding we'll use ListView's Binding capabilites as an example. Binding is similar among all Bindable controls, however, the parameters to the Bind will be tailored specifically to the Control.

Without Data Binding, if we wanted to populate a ListView with a list of data from a database we would have to manually iterate through the ComboBox and add Items.

$people = Data::$Links->MyDB->ExecFunction('sp_get_people', 10065);
$listView = new ListView();
$listView->Columns->AddRange('First Name', 'Last Name', 'Phone');
foreach($people as $person)
{    
    $row = new ListViewitem();
    $row->SubItems->AddRange($person['firstname'], $person['lastname'], 
    $person['phone'];
}

Note: The above could be expanded to longer code through the use of Add instead of AddRange.

While the above will populate the data, it only adds the information explictly retrieved and does not allow for a limited set, dynamic population as you scroll, or paging.

With Data Binding the above code will be greatly reduced while providing us with support for limited range, offsets, paging, scrolling, dynamic sorting, and even custom callback functionality.

/*Rather than execute our database function directly, we'll create a 
command to be used with our Bind. While we can pass in a result set 
from an ExecFunction, passing a command is more efficient since Bind 
will only retrieve the necessary rows instead of all resulting rows.*/
$people = Data::$Links->MyDB->CreateCommand('sp_get_people', 10065);
//Instantiates a ListView
$listView = new ListView();
$listView->Bind($people, array('firstname', 'lastname', 'phone'));

Our ListView is now bound to data from our function. By default ListView will load 50 rows at a time, this can be changed in the following manner:

//Our ListView will now load 20 rows at a time
$listView->Bind($people, array('firstname', 'lastname', 'phone'), 20);

We can also choose an offset for the data through the offset parameter.

//Our ListView will now load 20 rows at a time, but will start at the 10th row
$listView->Bind($people, array('firstname', 'lastname', 'phone'), 20, 10);

Callback

In many Data Binding situations you might want to manually handle each row of data. We can do this by using the callback parameter of our Bind function.

/*notice the last parameter is a ServerEvent, this is our Callback function
which will be called for each row of data*/
$listView->Bind($people, array('firstname', 'lastname', 'phone'), 20, 10, new ServerEvent($this, 'CreateRow'));
 
/*Our CreateRow function which will be used in conjuction with Bind,
  please note that our function MUST return an instance of ListViewItem*/
function CreateRow()
{
    //A variable containing the data for this row in an array
    $data = Event::$BoundData;
    $row = new ListViewItem($data);
    $row->BackColor = 'red';
    return $row;
}

It's important to realize that we can now do anything we like to each row of our ListView while still being bound to a dynamic data source.

function CreateRow()
{
    /*A variable containing the data for this row in an array,
      the data contained in this array varies based on the constraints.*/
    $data = Event::$BoundData;
    $row = new ListViewItem($data);
    $row->Click = new ServerEvent('System', 'Log', $data['firstname);
    $row->BackColor = 'red';
    return $row;
}

Furthermore, we can deviate from the row data and populate our row with our own values.

function CreateRow()
{
    /*A variable containing the data for this row in an array,
      the data contained in this array varies based on the constraints.*/
    $data = Event::$BoundData;
    //Unlike our previous examples we will not pass in $data to ListViewItem
    $row = new ListViewItem();
    //Rather, we'll add the SubItems ourselves, in this case the revese of the data
    $row->SubItems->Add(strrev($data['firstname));
    $row->SubItems->Add(strrev($data['lastname));
    $row->SubItems->Add(strrev($data['phone));
    $row->Click = new ServerEvent('System', 'Log', $data['firstname);
    $row->BackColor = 'red';
    return $row;
}

Constraints

You might have notices in the previous example our array of column names being passed to Bind. This array is an example of a Constraint. Constraints act as a filter for your Data Bind letting Bind know what specific Data you want to bind to.

For example, our previous array

array('firstname', 'lastname', 'phone')

lets bind know that you only care about the firstname, lastname and phone columns. However, if we wanted to bind to this data but have different column names we would need to elaborate on the constraints.

In ListView's case, its Constraints is an array, but Each constraint can also be an array detailing more information. A constraint can be a string which corresponds to a column name, or an array containing the bound column name, displayed column name, and width.

//Our Constraints array
$constraints = array();
//We can just bind to the column without a custom column name
$constraints[] = array('firstname')
//We can also bind to the column but with a custom column name
$constraints[] = array('firstname', 'First Name');
/*For those cases where you want to set a custom width for the column.
  In this case our column Width will be 300.*/
$constraints[] = array('firstname', 'First Name', 300);

Furthermore, there might be cases where you want Data in a Callback function, but don't want it do display in a column.

//This means to retrieve the person_id for callback, but don't display in a column
$constraints[] = array('person_id', false);
 
...
 
//Now in our Callback function we'll have access to person_id
function CreateRow()
{
    /*A variable containing the data for this row in an array,
      the data contained in this array varies based on the constraints.*/
    $data = Event::$BoundData;
    //Though it's accessible from $data, person_id will not show up as a column
    $row = new ListViewItem($data);
    //When the row is clicked we'll Log the person_id of the row
    $row->Click = new ServerEvent('System', 'Log', $data['person_id');
    $row->BackColor = 'red';
    return $row;
}

//Alternatively we can add a column that's not bound to any data

//This means to display the column Status, but is not bound to any data.
$constraints[] = array(false, 'Status');
//We can also set the width of this Column
$constraints[] = array(false, 'Status', 100);