This article describes Aggregate Charting, one of the cool new features introduced in ComponentOne Reports for WinForms in the 2009 v3 release.
ComponentOne Reports for WinForms has always supported chart fields using its extensible custom field architecture. The Chart field is implemented as a custom field in the C1.Win.C1Report.CustomFields.2.dll assembly, which is installed with the report designer application and is also included as a sample with full source code (CustomFields). In this article, you'll see how you can customize chart fields in reports using the C1ReportDesigner application. The C1ReportDesigner application is installed with both ComponentOne Reports for WinForms and ComponentOne Reports for WPF.
Creating a simple chart is very easy. Here are the steps required:
For example, the chart below was created based on the NorthWind Products table. In this case, the following properties were set:
DataX = "ProductName"
DataY = "UnitPrice"
Note that for this chart type (Bar), the value axis (where the DataY field is displayed) is the horizontal one, and the category axis is the vertical one.
In this case, a filter was applied to the data in order to limit the number of values shown. Without the filter, the chart would contain too many values and the vertical axis would not be readable.
In addition to the DataX and DataY properties mentioned above, the Chart object provides a few other properties that are commonly used:
These properties apply to all chart types. There are a few additional properties that only apply to Pie charts:
The Chart field is actually a wrapper for a C1Chart control, which provides all the charting services and has an extremely rich object model of its own. If you want to customize the Chart field even further, you can use the ChartControl property to access the inner C1Chart object using scripts.
For example, the Chart field does not have a property to control the position of the legend. But the C1Chart control does, and you can access this property through the ChartControl property. For example, the script below causes the chart legend to be positioned below the chart instead of on the right:
' place legend below the chart
chartField.ChartControl.Legend.Compass = "South"
If you assign this script to the report's OnLoad property, the chart will look like the image below:
The other properties used to create this chart are as follows:
ChartType = Pie
FormatY = "p1"
ShowPercentage = truePalette = "Red;Gold;Orange;Beige;DarkGoldenrod;Goldenrod;"
To create charts with multiple series, simply set the DataY property to a string that contains the names of each data field you want to chart, separated by semi-colons. For example, to create a chart showing product prices and discounts you would set the DataY property as shown below:
DataY = "UnitPrice;Discount"
If you want to specify the color used to display each series, set the Palette property to a list of colors separated by semi-colons. For example, the value displayed below would cause the chart to show the UnitPrice" series in red and the "Discount" series in blue:
Palette = "Red;Blue"
The DataY property is not restricted to field names. The strings that specify the series are actually treated as full expressions, and are calculated like any regular field in the report.
For example, to create a chart showing the actual price of each field you could set the DataY property to the value shown below:
DataY = "UnitPrice * (1 - Discount)"
Reports for WinForms allows you to create reports with multiple groups. For example, instead of listing all products in a single flat report, you could group products by category. Each group has a header and a footer section that allow you to display information about the group, including titles and subtotals, for example.
If you add a chart to a group header, the chart will display only the data for the current group. By contrast, adding a chart to the report header or footer would include all the data in the report.
Continuing with the example mentioned above, if you added a chart to the group header and set the DataX property to "ProductName" and the DataY property to "UnitPrice", the final report would contain one chart for each category, and each chart would display the unit prices for the products in that category.
The images below show screenshots of the report described above with the group headers, the charts they contain, and a few detail records to illustrate:
Chart showing unit prices for products in the "Beverages" category
Chart showing unit prices for products in the "Condiments" category
DataX = "Product Name"
DataY = "Unit Price"
Because the chart automatically selects the data based on the scope of the section that contains it, creating charts in grouped reports is very easy.
The Chart field included with the 2009 v3 release of Reports for WinForms has a powerful new feature called "aggregated charting". This feature allows you to create charts that automatically aggregate data values (DataY) that have the same category (DataX) using an aggregate function of your choice (sum, average, standard deviation, and so on).
To illustrate this feature, consider an "Invoices" report that groups data by country, customer, and order ID. The general outline for the report is as follows:
Now imagine that you would like to add a chart to each Country header displaying the total value of all orders placed by each customer in the current country.
You would start by adding a Chart field to the "Country" header section and then setting the DataX and DataY properties as follows:
DataX = "CustomerName"
DataY = "ExtendedPrice"
This would not work. The data for each country usually includes several records for each customer, and the chart would create one data point for each record. The chart would not be able to guess that you really want to add the values for each customer into a single data point.
To address this scenario, we added an Aggregate property to the Chart field. This property tells the chart how to aggregate values that have the same category into a single point in the chart. The Aggregate property can be set to perform any of the common aggregation functions on the data: sum, average, count, maximum, minimum, standard deviation, and variance.
Continuing with our example, we can now simply set the chart's Aggregate property to "Sum". This will cause the chart to add all "ExtendedPrice" values for records that belong to the same customer into a single data point. The result is shown below:
Notice how each customer appears only once. The values shown on the chart correspond to the sum of the "ExtendedPrice" values for all fields with the same "Customer".
Because the chart appears in the "Country" header field, it is repeated for each country, showing all the customers in that country.
If you place the chart in the report header section, it will aggregate data over the entire report. For example, suppose you want to start the "Invoices" report with a chart that shows the total amount ordered by each salesperson. To accomplish this, you would add a Chart field to the report header section and would set the following properties:
DataX = "Salesperson"
DataY = "ExtendedPrice"
Aggregate = "Sum"
The image below shows the resulting chart:
Since the chart is placed in the report header section, the values displayed include all countries and all customers. If you moved the chart field from the report header to the "Country" group header, you would obtain a similar chart for each country, showing the total amounts sold by each salesperson in that country.
Aggregate charting is a powerful, yet simple and easy-to-use feature. We hope you enjoy it and use it to create spectacular reports!
ComponentOne Reports for WinForms is part of ComponentOne Studio for WinForms. If you have not already, download the latest trial version at http://www.componentone.com/SuperProducts/StudioWinForms/ so you can start creating your reports.