Bind Report Controls to Data

This topic describes how to bind report controls to data fields at design time and runtime.

General Concepts

Do the following before providing data to controls in Visual Studio Report Designer and End-User Report Designers:

  • Bind your report to a data source.

    Refer to the Quick Guide to Report Data Sources topic for more information.

  • Set data binding mode.

    • Expression Bindings mode (default) - enables you to use complex expressions that include two or more fields and various functions. Expressions allow you to calculate complex summaries without scripts and conditionally shape your data without formatting rules.

    • Standard Data Binding mode - enables you to provide data to a report control by assigning an appropriate field or using report scripts in complex scenarios.

    Refer to the Data Binding Modes topic for details.

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 all binding modes.

Dropping a data field onto a report's surface creates a new report control bound to the corresponding field.

DesignTimeFeatures - FieldList2.png

Dropping a data field onto an existing control binds this control to the corresponding field.

DesignTimeFeatures - FieldList3.png

See the Field List document for more information about using this panel for data binding.

Note that while binding, the field is assigned 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, and combine static and dynamic content in the same control (for instance, to append a 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. This tab provides properties specified using expressions with available data fields.

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.

label-expression-editor-complex-binding

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.

label-smart-tag-expression-drop-down

After you bind the report control to data, you can format the control's values using the Format String option (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 Shape Data (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:

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.

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.

How to -  BindControl2DataField_1a

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.

How to -  BindControl2DataField_1

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.

DataBinding - ReportControls4 (DesignUnBinding)

Runtime Specifics

The XRControl.DataBindings collection stores all control bindings (XRBinding objects). You can bind a control to a data field at runtime by creating an XRBinding object with the 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 are rendered in Print Preview based 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 the remaining bands display the current record's content.

The following image illustrates the report layout and its result in Print Preview:

Report Designer Print Preview
DataBinding - ReportControls5 (Bands) DataBinding - ReportControls6 (Bands)

See Introduction to Banded Reports for more information.

See Also