Extending C1Report with Custom Chart and Gradient Fields
Extending C1Report with Custom Chart and Gradient Fields
||Reports for .NET
The 2004 v3 release of ComponentOne Reports for .NET added support for custom report fields. These fields are contained in separate assemblies registered with the Report Designer, and can be used in reports without any additional work.
C1Report includes a CustomFields assembly with two custom fields: Chart and Gradient (the full assembly name is C1.Win.C1Report.CustomFields.dll).
The CustomFields assembly source code is available, and can be used as a reference in case you want to create specialized versions of the custom fields provided or to create new custom fields of your own.
Download source code (C#)
Custom fields can also be used in ASP.NET applications. The C1WebReport control supports all C1Report features.
Using Chart Fields
Chart fields are implemented using the C1Chart control (you must deploy the C1Chart assembly with your application if you use charts).
To add a Chart field to your report, open the report in the Report Designer, click the Chart field in the toolbar, and mark the area in the report where the Chart should be displayed. Then set the field properties as usual.
The only unusual aspect of Chart fields is that unlike most bound fields, they display multiple values. To select the data you want to display, you should set the Chart field's DataX and DataY properties. You can also customize the chart appearance by setting other properties such as ChartType, Palette, etc.
The following tutorial walks through the creation of a report with an embedded chart:
Step 1: Use the Report Wizard to create a new report
Use the Wizard to select a data source for the report. In this tutorial, we will use the NorthWind database and the "Sales by Category" view. The picture below shows this step:
Next, select the fields that you want to display. In this tutorial, we will group the data by Category and show ProductName and ProductSales in the detail section of the report: To add groups and detail fields, drag them from the "Available" list on the left to the "Groups" or "Detail" lists on the right:
Click "Next" until the wizard is done to finish creating the initial version of the report.
Step 2: Add the Chart to the Group Header section of the report
Charts usually make sense in the group header sections of a report, to summarize the information for the group. To add the chart, start by making some room for it in the group header section, then click the Chart button in the field toolbar and place the field in the report. This is what the report should look like at this point (note that the Chart button is pressed in the image):
The chart is not visible yet because there's no data attached to it. Select the chart field and scroll the property window to see the properties in the "Chart" category (switch the property grid to category view and turn off the property filter if necessary).
Set the DataY property to the name of the field that contains the values to be charted. In this case, ProductSales. Also set the DataX property to the name of the field that contains the labels for each data point. In this case, ProductName.
Note that the DataY property may specify more than one chart series. Just add as many fields or calculated expressions as you want, separating them with semicolons.
The Chart control will now display some sample data so you can see the effect of the properties that are currently set (the actual data is not available at design time). You may want to experiment changing the values of some properties such as ChartType, ForeColor, DataColor, and GridLines. You can also use the regular field properties such as Font and ForeColor.
When you are satisfied with the Chart settings, click the Preview button to see the report. It should look like this:
Note that the Report field is sensitive to its position in the report. Because it is in a group header section, it only includes the data within that group. If you place the Chart field in a detail section, it will include all the data for the entire report. This is not useful because there will be one chart in each detail section and they will all look the same. (If you need more control over what data should be displayed in the chart, you can use the DataSource property in the chart field itself. That is discussed later, in the Chart field reference).
You can now save the report and use it in your WinForms and ASP.NET applications.
Using Gradient Fields
Gradient fields are much simpler than charts. They are mainly useful as a background feature to make other fields stand out.
For example, add a gradient field over the labels in the group header section. You may have to right-click the field and select Send To Back to ensure it is behind the labels. Then set the ColorFrom and ColorTo properties to Red and White, and set the Angle property to -90.
Gradients can make reports look more appealing (especially if you are a good graphics designer, of course):
Chart Field Reference
This class inherits from C1Report.Field and uses the C1Chart control to embed data bound charts in reports. The Chart class has the following properties (in addition to the ones provided by the base class Field):
|ChartTypeEnum ChartType||Gets or sets the chart type. Available types are Bar, Area, Scatter, and Pie.|
|string RecordSource||Gets or sets a Sql statement to use and retrieve data for the chart. If provided, data is retrieved using the parent report's ConnectionString. If omitted, data is retrieved directly from the parent report. In this latter case, the data is automatically filtered according to the current grouping scope (for example, a chart in a 'Category' group header would contain data only for the current category).|
|string DataX||Gets or sets a string containing one field with the chart labels. Labels are displayed along the X axis or along with pie slices. For example:|
|chartField.DataX = "ProductName"|
|string DataY||Gets or sets a string containing one or more fields with the data to plot on the chart. If multiple fields are provided, they must be separated with semicolons. For example: |
|chartField.DataY = "UnitPrice;UnitsInStock"|
|You can also use regular VBScript expressions instead of simple field names. For example, to plot sales and sales taxes as two separate series, you could use:|
|chartField.DataY = "Sales;Sales * 0.085"|
|bool RadialLabels||This property only applies to Pie charts. It causes the field to add radial labels attached to the pie slices instead of a legend. |
|bool ShowPercentages||This property only applies to Pie charts. It causes the field to add percentage labels to the pie slices.|
|bool GridLines||Adds gridlines to charts. This property does not apply to Pie charts.|
|bool Boxed||Draws a box around the plot area.|
|bool Use3D||Applies 3D effects to the charts.|
|Color DataColor||Specifies the color for the chart bars, lines, symbols, or pie slices. If the chart contains more than one series (or pie slices) then additional colors are generated automatically by making the base color lighter. To control the color of each series in a multi-series chart, use the Palette property instead.|
|string Palette||Specifies a collection of colors to be used for each series (or pie slices). The collection is specified as a string containing a list of color names, delimited by semicolons. For example:|
|chartField.Palette = "Red;Green;Blue".|
|C1.Win.C1Chart.C1Chart ChartControl||Provides access to the underlying C1Chart control and its object model. You can set properties in the underlying C1Chart control using script or code, but these properties are not persisted when the report is saved.|
Gradient Field Reference
This class inherits from C1Report.Field and uses a LinearGradient brush to draw a gradient background. If the field contains text, that is also displayed. The Gradient class has the following properties (in addition to the ones provided by the base class Field):
|Color ColorFrom||Initial color for the gradient background.|
|Color ColorTo||Final color for the gradient background.|
|int Angle||Angle for the gradient pattern, in degrees.|
Custom Field Reference
Custom fields are public classes that inherit from the C1Report.Field class and override the GetRenderContent method to provide custom text or images to be rendered in the report. The method signature is as follows:
override protected void GetRenderContent(
ref string value,
ref Image img,
The custom field has access to the containing report (through the ParentReport property) and should use that to determine what to display. The field can then set the value or image parameters and the containing report will render the returned values in the report.
The last parameter allows the field to render differently at design time or run time. This is usually needed for bound controls, since no data is available at design time.
In addition to overriding the GetRenderContent method, custom fields may expose any public properties that may be needed to define the field content (for example, ChartType). Public properties are automatically persisted by the designer within report definition files.
To integrate within the Report Designer, custom fields should also contain a Description attribute, and their containing assembly should have an embedded bitmap resource with the same name as the field. This allows the Report Designer to show the custom field in its own toolbar.
For example, the Chart field has the following description attribute:
public class Chart : C1.Win.C1Report.Field
The containing assembly (C1.C1Report.CustomFields.dll) has an embedded bitmap resource named "Chart". The bitmap should be 13 pixels high by 14 pixels wide, and the transparent color used is Red. The bitmaps used for the Chart and Gradient fields look like this:
The final step required for integration is the addition of an entry to the Report Designer configuration file. The configuration file is called C1ReportDesigner.exe.settings, and is located in the Report Designer directory.
To add new custom fields to the configuration file, you must add them to the customfields xml node. Each entry in the customfields node is an item node with a string value that contains the name of the assembly that implements the field and the full name of the custom field class, separated by a semicolon. For example, the entries that add the Chart and Gradient fields look like this in the configuration file:
<!-- custom fields
Custom fields must derive from the C1Report.Field class. Entries contain:
<item value="C1.Win.C1Report.CustomFields;C1.Win.C1Report.CustomFields.Chart" />
<item value="C1.Win.C1Report.CustomFields;C1.Win.C1Report.CustomFields.Gradient" />