ControlId=\ BindingSource=\
BindingSourceMember=\ ErrorMessageLocation=\ ... more DataBindingItems
The collection establishes the individual bindings that are applied by the DataBinder. While wwDataBinder extends existing controls, nothing is actually extended until you explicitly set properties on the DataBindingItem extender property of any given control on the form.
In design mode, the extender exposes a DataBindingItem property-this is for providing a mapping between a data item and a control property. Supported data items are ADO.NET data objects, such as ADO.NET DataRow fields. Alternatively, you can bind to an object and any simple property of an object that can be referenced
through
the
Page
object.
It's
possible
to
bind
this.Customer.Entity.CompanyName, where this refers to the Page object (which is the base object from which any binding expression originates).
Binding is performed using a BindingSource to identify a data item. The BindingSource consists of two properties-BindingSource (which is a string property that describes the base object) and BindingSourceMember (which provides the mapping of the field or property to bind to). Programmatic access can also make use of the BindingSourceObject property to provide a reference instead of a BindingSource string.
Suppose you want to bind to a DataRow object. In order for wwDataBinder to bind to the DataRow, the DataRow needs to be accessible through a Page reference. So this.MyDataRow works. In this case, you'd bind with:
BindingSource: MyDataRow
BindingSourceMember: CompanyName
- 11 -
As shown here, CompanyName is the name of the field to which you should bind.
Also, this.Customer.DataRow will work, where Customer is a business object that has a DataRow property. Here, you'd bind with:
BindingSource: Customer.DataRow BindingSourceMember: CompanyName
You can bind to a DataTable in the same way. When a DataTable or DataSet is used as the BindingSource object, wwDataBinder assumes the first DataRow for a table or the first table and first DataRow for a DataSet. You can also bind an ADO.NET object more directly, like so:
BindingSource: MyDataSet.Tables[\BindingSourceMember: CompanyName
Just remember that in order for the wwDataBinder to be able to bind, whatever object you're binding to must be referenced through a property of the Page that is marked as protected or public. Public is preferred since public reflection is supported in Medium Trust, whereas reflection will fail with protected properties. Private properties are not supported for binding.
In addition to ADO.NET types, you can also bind to business entities or types from the .NET Base Class Library (BCL). For example, if you have a business object that lets you access CompanyName with this.Customer.Entity.CompanyName, you can express the BindingSource as:
BindingSource: Customer.Entity BindingSourceMember: CompanyName
You can also bind directly to Page object members. If you have a DateTime
- 12 -
RightNow property on the Page then binding looks like the following:
BindingSource: this
BindingSourceMember: RightNow
Any BindingSource implicitly uses this or me to signify the Page object. But unless you are using the Page itself as the binding source, these are optional and don't need to be specified. A BindingSource is relative to a top-level container object-typically the ASP.NET Page object-but you can supply the top-level container as part of the DataBind and Unbind methods as a parameter. This is useful if you want to use the wwDataBinder in a user control where the top-level container is the UserControl rather than the page.
BindingSourceMembers are always simple types like ints, strings, DateTime, bool, and so on. They can also be Enum values, which are translated into strings and work for two-way binding.
The job of a BindingSource is to establish a binding between a data item or property and the control property to which the value is bound. This mapping is used both for binding to a control property and from a control property back into the data item
or
property.
Inbound
binding and
is
established
is
by done
calling by
the
wwDataBinder.DataBind method, unbinding calling
wwDataBinder.Unbind. The process is deterministic in that you explicitly call these methods from your code-this provides a lot of flexibility in terms of how binding is handled.
A DataBindingItem exposes additional properties that are associated with the data binding process, as shown in Figure 1. The BindingProperty determines the field of the control you are binding to-the default is Text, but if you're binding to a CheckBox, you likely bind to Checked or if you're binding to a list control to SelectedValue.
Data binding can be one-way, two-way, or none. Input controls like textboxes generally use two-way binding, while display controls like labels use one-way binding. None is useful if you want a control to participate in binding error management, but you don't want to bind the control to a value.
- 13 -
The wwDataBinder control automatically manages both binding and unbinding errors. When a control cannot be bound or unbound, the control generates a BindingError in the BindingErrors collection, but no exception fires. You can query this collection for individual binding errors and retrieve a summary of errors with the ToHtml method. By default, each control with an error also displays an error icon next to it. Figure 2 shows an example of the form with a few binding errors.
Figure 2 Displaying Binding Errors (Click the image for a larger view)
BindingErrors can either be automatically generated by the control during the binding or unbinding process or can be manually added to the BindingErrors collection from your own code. Automatic BindingErrors are generated when an input value cannot be converted back to the bound data item or property, usually due to a data conversion error. For example, the Reorder Expected date shown in Figure 2 is an invalid date and the error is automatically captured by the control since the date conversion fails. Each DataBindingItem also has an IsRequired property and, not surprisingly, an item marked as IsRequired cannot be left blank. If one is left empty, a binding error is automatically generated and added to BindingErrors.
- 14 -
The other two errors on this form are manual errors. The Dairy Products error is handled through a ValidateControl event that is hooked up to the wwDataBinder. The event fires for each control bound and the event handler allows for checking each control after it has been unbound. If you decide a value is not valid in your code, you can set the BindingItem's BindingErrorMessage programmatically and return false to let the binder know that this DataBindingItem is in error and needs to display on the error list.
The last error is a purely programmatic error that is added by using wwDataBinder.AddBindingError and specifying the error message and Control instance or ID in the Page code. This allows assigning an arbitrary error message to a control that is data bound and makes the control show up both with the icon and in the error listing.
All of this provides for automatic and fully programmatic binding error generation so there's lots of flexibility on how errors and error icons are displayed. In addition, the control automatically picks up any Validator controls on the page and picks up their error messages and control IDs and incorporates them into the binding error mechanism.
If a control has an error, an icon is displayed next to it by default. The icon display is optional and you can turn off the warning icons for the DataBinder as a whole, or you can change the location and format for each of the individual DataBindingItems through the ErrorMessageLocation property. By default, a WebResource is used-it points to an embedded image resource in the compiled control assembly. Or you can override the image explicitly with the ErrorIconUrl property on wwDataBinder.
The assembly also includes a wwErrorDisplay control, which is used to display the error summary shown in Figure 2. This control is optional, but I like to use it for consistency. In the example, I have simply assigned the BindingErrors.ToHtml method's string output to the text property. The control also has easy message display methods, like ShowError and ShowMessage, which display one-line messages with an icon, providing a consistent way to display messages on a Page.
You'll notice that the error summary has links for each error displayed. These links jump to the individual control that is in error and highlight it, making it easier to
- 15 -
spot and fix errors.
- 16 -