Binding Reports to a Data Source

There are several ways to create data-bound contents in a MindFusion.Reporting report. The majority of the data-binding mechanisms involve the use of one or more DataRange objects. It is also possible to create data-bound Chart objects outside of data ranges.

Note
The sections below assume you are already acquainted with the process of adding data sources to a .NET application. For a step-by-step tutorial on how to do this, refer to Tutorial 1: Getting Started.

Using DataRange objects

In order to perform data-binding you have to create a DataRange object and add it to the report. Then assign the appropriate data source to the DataSource property of the data range and the name of the respective data member (usually table or view) to its DataMember property. You can do this either from the property grid in the report designer or directly via code.

In the following example a data range is bound to the Employees table in an existing data set:

C#

this.dataRange1.DataSource = this.nwindDataSet1;
this.dataRange1.DataMember = "Employees";

Visual Basic

Me.dataRange1.DataSource = Me.nwindDataSet1
Me.dataRange1.DataMember = "Employees"

The above code assumes that dataRange1 identifies the existing DataRange object and nwindDataSet1 - an existing .NET DataSet object.

Once the data range is bound to a data source, you can associate the report items contained in that data range with individual fields in the bound data member by assigning the name of the field to the item's DataField property. In the example, if we assume that we have a label label1 within the data range, we can associate this label with the 'FirstName' field in the Employees table by assigning 'FirstName' to the label's DataField property:

C#

this.label1.DataField = "FirstName";

Visual Basic

Me.label1.DataField = "FirstName"

When running the report, the data range will be multiplied as many times as there are records in the Employees table. The label1 in each occurrence of the data range will contain the 'FirstName' of the employee from the corresponding record.

Note
Currently, it is not possible to create data-bound DataRange objects within headers and footers.

For a step-by-step example on how to create data-bound reports using data ranges, see Tutorial 2: Binding to a Data Source.

Master detail relation

MindFusion.Reporting supports master detail relation through data range composition. You need to create a data range, bound to one of the data members. Then you need to create another data range as a child of the first one, bound to the data member related to the first one. Finally, you have to specify the name of the relation as a value to the MasterDetailRelation property of the inner data range. The following code illustrates this:

C#

this.innerRange.DataSource = this.nwindDataSet1;
this.innerRange.DataMember = "Products";
this.innerRange.MasterDetailRelation = "CategoriesProducts";

this.outerRange.DataSource = this.nwindDataSet1;
this.outerRange.DataMember = "Categories";
this.outerRange.Items.Add(this.innerRange);

Visual Basic

Me.innerRange.DataSource = Me.nwindDataSet1
Me.innerRange.DataMember = "Products"
Me.innerRange.MasterDetailRelation = "CategoriesProducts"

Me.outerRange.DataSource = Me.nwindDataSet1
Me.outerRange.DataMember = "Categories"
Me.outerRange.Items.Add(Me.innerRange)

The code makes many assumptions including the correctness of the DataRange objects referenced by innerRange and outerRange and the availability of the 'Categories' and 'Products' data members within the specified data set.

Data range composition can be achieved very easily through the Report Designer by dragging the inner data range to the outer one.

Automation

It is possible to create data-bound DataRange objects automatically within the Report Designer. This automatic creation involves setting up the DataSource and DataMember properties of the data range automatically as well as adding one or more labels representing individual data fields to the new data range. It is also possible to create a header, containing static label texts with the names of the individual columns.

To create a data-bound DataRange object right-click anywhere on the page surface in the report designer and select the 'Create DataRange from Adapter...' command from the context menu. This command displays a dialog box with the table adapters currently available in the report. In order for this to work, you have to have created at least one data adapter in the report from which to create the new data range. The following image shows how this dialog box looks like:

You need to select the fields you want to be present in the data range and whether the data range should have a header or not. The labels representing the selected fields are evenly distributed along the width of the newly created data range.

For a step-by-step example on how to use this automation option, visit Tutorial 1: Getting Started.

Data-binding Chart objects

There is one type of MindFusion.Reporting elements that can be data-bound without the need to place them in a data-bound DataRange object, namely, the classes deriving from Chart - BarChart, LineChart, PieChart and RadarChart. For more information about those elements and how you can use them in reports, check Charts in Reports.

As with data ranges, you can bind Chart objects by using their DataSource and DataMember to specify the data source and member respectively. Then you need to assign the field to bind to through the appropriate property. If you want to data-bind a BarChart object, you should assign the name of the data field to its DataFields property. If you want to bind a PieChart, you should assign to its DataField property. To bind a LineChart, use its XDataFields and YDataFields properties. Finally, to bind a RadarChart, use its DataFields property.

For example, the following code binds the BarChart object referenced by the variable barChart1 to the field "UnitPrice" in a table "Products" of a data source identified by a .NET DataSet referenced by the variable dataSet1:

C#

this.barChart1.DataFields = "UnitPrice";
this.barChart1.DataMember = "Products";
this.barChart1.DataSource = this.dataSet1;

Visual Basic

Me.barChart1.DataFields = "UnitPrice"
Me.barChart1.DataMember = "Products"
Me.barChart1.DataSource = Me.dataSet1

The Chart objects provide other properties that can be data-bound. For example, the XLabelsFields property of the BarChart class can be set to the name of the field to supply the texts of the labels across the x-axis. In order for this binding to work, you also have to set the LabelType property of the XAxisSettings property of the BarChart class to CustomText. Here is how you can do this in code:

C#

this.barChart1.XLabelsFields = "ProductName";
this.barChart1.XAxisSettings.LabelType = MindFusion.Charting.AxisLabelType.CustomText;

Visual Basic

Me.barChart1.XLabelsFields = "ProductName"
Me.barChart1.XAxisSettings.LabelType = MindFusion.Charting.AxisLabelType.CustomText