Multi-Value Report Parameters
- 5 minutes to read
This document describes how to create a multi-value parameter and filter report data by the specified parameter values.
Tip
See Specify Query Parameters for information on how to use multi-value parameters in an SQL query.
Create a Multi-Value Parameter
Follow these steps to create a multi-value parameter at design time:
Create a report parameter and enable the Allow multiple values option (corresponds to the Parameter.MultiValue property).
Specify a list of predefined values for the parameter. See the following topics for more information:
- Report Parameters with Predefined Static Values - to directly specify the list of values.
- Report Parameters with Predefined Dynamic Values - to specify the storage that contains the list of values.
To create a multi-value report parameter in code, follow the steps below.
- Create a StaticListLookUpSettings or DynamicListLookUpSettings class instance and configure it with a set of predefined parameter values.
- Assign the newly created instance to the parameter’s ValueSourceSettings property.
- Enable the parameter’s Parameter.MultiValue property. It allows the parameter to have more than one value.
Note
A complete sample project is available on Github: How to assign multiple values to a report parameter from a connected data source
using System;
using System.Windows.Forms;
using DevExpress.XtraReports.Parameters;
// ...
// Create a parameter and specify its name.
Parameter parameter1 = new Parameter();
parameter1.Name = "CategoryIDs";
// Specify other parameter properties.
parameter1.Type = typeof(System.Int32);
parameter1.MultiValue = true;
parameter1.Description = "Categories: ";
DynamicListLookUpSettings lookupSettings = new DynamicListLookUpSettings();
lookupSettings.DataSource = report.DataSource;
lookupSettings.DataMember = "Categories";
lookupSettings.DisplayMember = "CategoryName";
lookupSettings.ValueMember = "CategoryId";
parameter1.LookUpSettings = lookupSettings;
parameter1.Visible = true;
parameter1.SelectAllValues = true;
report.FilterString = "CategoryName in (?CategoryIDs)";
Filter a Report by a Multi-Value Parameter
Use the Is any of operator in the report’s filter string:
To filter report data in code, specify the report’s FilterString property.
using DevExpress.XtraReports.UI;
using DevExpress.XtraReports.Parameters;
// ...
// Create a parameter and specify its name.
Parameter parameter1 = new Parameter();
parameter1.Name = "CategoryIDs";
Parameter1.Visible = true;
//...
// Filter report data
report.FilterString = "CategoryName in (?CategoryIDs)";
The filtered report is displayed after a user specifies parameter values.
Pre-Select Parameter Values
Use one of the following methods to pre-select multiple parameter values when a report is first rendered.
Assign an array of values to the Default Value (corresponds to Parameter.Value) property.
Set the Expression property to an expression that evaluates to an array of values. You can use data source fields and other parameters in expressions.
Enable the Select all values property to populate the parameter value with all items from its data source (static or dynamic).
Tip
Disable the report’s RequestParameters property to avoid the Waiting for parameter values message in Preview and display the report with pre-selected parameter values.
The following example illustrates how to pre-select values for a multi-value report parameter in code:
using System;
using System.Windows.Forms;
using DevExpress.XtraReports.Parameters;
// ...
// Create a report instance.
XtraReport report = new XtraReport();
// Add a parameter to the report.
report.Parameters.Add(
new Parameter() {
Name = "category",
Type = typeof(System.Int32),
MultiValue = true,
ValueSourceSettings = new DynamicListLookUpSettings() {
DataSource = report.DataSource,
DataMember = "Categories",
ValueMember = "CategoryID",
DisplayMember = "CategoryName",
SortMember = "CategoryName",
SortOrder = DevExpress.Data.ColumnSortOrder.Ascending
}
});
// Specify parameter values.
report.Parameters["category"].Value = new int[] { 1, 2, 3 };
Note
Parameter values should match the parameter’s type.
Optional Multi-Value Parameter
You can leave the parameter unspecified and display all report data. A user optionally chooses parameter values to filter the report.
Do the following to make a multi-value parameter optional.
Configure the parameter as follows:
| Property | Value |
|---|---|
| Allow null value | true |
| Default Value | Not specified |
| Expression | Not specified |
| Select all values | false |
Disable the report’s RequestParameters property.
Use the following report filter string:
?category Is Null or [Category ID] In (?category)
Tip
You can also use the filter string shown above to filter report data at the data source level. See the Specify Query Parameters topic for more information.