Binding data with a custom sub-entity

Custom sub-entities use the Act! DataList class as its base data binding mechanism. The CustomEntityList class supports .NET data binding for lists of data as well as individual columns.

With the addition of alias to column names custom sub-entities can support standard .NET windows forms data binding using the BindingSource class.

BindingSource is in the System.Windows.Forms namespace and was added in the 2.0 release of .NET. BindingSource provides a lot of the data binding functionality that previously would have had to been coded everywhere data binding was used.

From the .NET SDK docs:

BindingSource simplifies binding controls on a form to data by providing currency management, change notification, and other services between Windows Forms controls and data sources. This is accomplished by attaching the BindingSource component to your data source using the DataSource property.

Binding custom sub-entities to a list control

After retrieving a CustomEntityList from the CustomSubEntityManager you can bind the list directly to a list control. Set the DataSource property of the control to the CustomEntityList. If you have added fields to the FieldDescriptors property of the list, you should see those columns in the control.

DataGridView is a .NET 2.0 Windows forms control that can be used to data bind to an Act! DataList.

Another way you can bind the CustomEntityList to the list control is with the BindingSource class. Create a BindingSource object and set the DataSource property of the BindingSource object to the CustomEntityList. Then set the list control’s DataSource property to the BindingSource object. The reason for using BindingSource is if the CustomEntityList will also be bound to individual controls for row editing and you want the grid and the controls to be in sync.

Binding custom sub-entities to individual controls

To bind a CustomEntityList row to individual controls, use the BindingSource class. Create a new BindingSource and set the DataSource property of the BindingSource to the CustomEntityList.

Next bind the individual control to the field using a new instance of Binding. When creating the Binding class instance use the BindingSource as the source for the binding and use a fields alias as the name of the property to bind to.

C# Example:

// bind a check box to the private field.

privateCheckBox.DataBindings.Add("Checked", bindingSource, "PRIVATE");

// bind a text box to the account name field

policyNameTextBox.DataBindings.Add("Text", this.bindingSource, "ACCOUNT_NAME", false, DataSourceUpdateMode.Never);

This binds the boolean property Checked for a checkbox to the CustomEntityList that is the data source for the bindingSource object and the field with the alias PRIVATE is used.

When binding fields to individual controls, if you want to do validation it’s best to use the overload of Add that takes a DataSourceUpdateMode enumeration at the end.

With this overload you can specify DataSourceUpdateMode.Never so those controls can be validated before sending the changes back to the data source.

Once you have validated the value in a control, you can manually call and have it post the data back to the data source.

C# Example:

// Write the value from the control to it's databound property descriptor.

control.DataBindings[0].WriteValue();

This would usually be done in the form's validated event handler.

Check the .NET 2.0 SDK for the Binding class for more information on data binding.