Binding Report Controls to Data
- 5 minutes to read
This topic describes how to bind report controls to data fields at design time and runtime.
General Concepts
Before providing data to report controls both in Visual Studio Report Designer and End-User Report Designers, you should bind your report to a data source. Refer to Quick Guide to Report Data Binding for details on this.
DevExpress Reports provide two different data binding modes:
- Expression Bindings - allow you to provide field values to a target report control’s properties without using report scripts.
- Standard Data Bindings - enable you to assign field values to a limited number of bindable properties.
The static UserDesignerOptions.DataBindingMode property defines which binding mode your report uses.
After connecting a report to data, the Field List panel displays the data source’s hierarchy and provides access to the available data fields. This panel allows you to bind report controls to data in several ways, each of which can be used in all binding modes.
Dropping a data field onto a report’s surface creates a new report control bound to the corresponding field.
Dropping a data field onto an existing control binds this control to the corresponding field.
You can also create specific types of controls and select multiple data fields at a time. See the Field List document to learn more about using this panel for data binding.
Note that all these ways assign the field to the control’s property with the DefaultBindableProperty attribute (usually, XRControl.Text).
You can also bind a control to the calculated fields and report parameters as well as combine both static and dynamic content within the same control (for instance, to append some text prefix or postfix to a value obtained from a database).
Expression Bindings
When the UserDesignerOptions.DataBindingMode is set to DataBindingMode.Expressions or DataBindingMode.ExpressionsAdvanced, a report uses expressions to provide data to controls.
In these modes, the Properties grid contains the Expressions tab providing properties for which you can specify custom expressions with the available data fields.
The DataBindingMode.Expressions (simplified) is the default binding mode, in which you can provide data to report controls in the XRControl.BeforePrint event.
The DataBindingMode.ExpressionsAdvanced mode allows you to provide data to report controls in the XRControl.BeforePrint and XRControl.PrintOnPage events.
You can also access expressions for the most popular properties using the control’s smart tag. Clicking the property’s ellipsis button invokes the Expression Editor in which you can specify the required data field or construct a complex binding expression involving two or more data fields.
You do not need to run the Expression Editor if you want to bind a report control to a single data field. Click the control’s smart tag, invoke the Expression‘s drop-down list and select the required field.
After you bind the report control to data, you can format the control’s values using the XRControl.TextFormatString property.
You can also use a binding expression to shape report data (for instance, calculate summary results or conditionally format data). See the Shaping Data using Expression Bindings documentation section for more information.
Runtime Specifics
The XRControl.ExpressionBindings property provides access to the control’s expression bindings. An ExpressionBinding object implements each expression binding’s functionality and contains the following settings:
- ExpressionBinding.EventName - specifies the event handler that evaluates the expression.
- ExpressionBinding.PropertyName - defines the property to which the expression is applied.
- ExpressionBinding.Expression - specifies the expression itself.
You can specify a report control’s binding expression at runtime by creating an ExpressionBinding object with the required settings and adding it to the XRControl.ExpressionBindings collection. The following code snippet demonstrates how to specify a custom expression for a label’s XRControl.Text property. This code assumes that a report is bound to a data source containing the UnitPrice and UnitsInStock fields.
using DevExpress.XtraReports.UI;
public XtraReport1() {
// ...
ExpressionBinding expressionBinding = new ExpressionBinding("BeforePrint", "Text", "[UnitPrice]*[UnitsInStock]");
xrLabel1.ExpressionBindings.Add(expressionBinding);
}
Legacy Data Bindings
When the UserDesignerOptions.DataBindingMode is set to DataBindingMode.Bindings, you can set a control’s bindable properties to the report’s data source fields.
The set of bindable properties differs depending on the control type. The Properties grid’s Data Bindings group provides access to these properties. Choose the property you want to bind and select the required data field in the drop-down list.
You can click the control’s smart tag and bind the most popular binding properties to data. Invoke the Data Binding option’s drop-down list and select the field.
You can also specify the output values’ format using the XRBinding.FormatString property.
To unbind a control’s property, invoke the binding drop-down list and select None.
Runtime Specifics
The XRControl.DataBindings collection stores all control bindings, each of which is implemented by the XRBinding class. You can bind a control to a data field at runtime by creating an XRBinding object with appropriate settings and add it to the collection (for instance, using the XRBindingCollection.Add method).
The following code snippet illustrates how to bind a label control to the Categories table’s CategoryName data field:
using DevExpress.XtraReports.UI;
// ...
XRBinding binding = new XRBinding("Text", this.DataSource, "Categories.CategoryName", "Category: {0}");
xrLabel1.DataBindings.Add(binding);
Control Behavior on Different Bands
Data-bound report controls’ rendering in Print Preview depends on the controls’ band type. Only the detail and group bands can display dynamic data source content. Controls in the Detail band are printed for each record in the assigned data source. The group bands contain controls whose values are used as grouping criteria. Controls bound to data and placed in remaining bands display the current record’s content.
The following image illustrates the report layout and its rendering result in Print Preview:
| Report Designer | Print Preview |
|---|---|
 |
 |
See Introduction to Banded Reports for more information.