Approaches for Adding Report Parameters

What is a Report Parameter?

Report Parameters allow you to control the report's content, connect related reports, or use them as arguments in functions. They typically filter report data that is retrieved from a data source component. Filtering data at the data source can improve performance for processing and viewing a report.

For the times when you cannot filter data at the source, you can use parameters to filter report data after it is retrieved. You can also sort and group data in a report based on report parameters.

Report Parameters can also be used to allow for user-input data when the report is displayed in a report viewer.

Add a Report Parameter using Report Designer

There are several ways to add a Report Parameter to the Report depending on the preferred designer:

Desktop Report Designers

1. Invoke the ReportParameter Collection editor with one of the following approaches:

   • Using the Report.ReportParameters property in the property grid.
   • Select the Report Parameters... option from the Context Menu
   • Right click on the [Parameters] node of the Report Explorer
   • From the Configure Data Source Parameters step of the DataSource Components

   

2. Click the Add button to create a new parameter.

Web Report Designer

1. Expand the DATA node of the Report Explorer properties to view the inner node Report parameters.
2. Click on the + sign beside Report parameters to create a new parameter and open the dialog with its properties.

Configure the Properties of a Report Parameter using Report Designer

1. In Name, type the name of the parameter.
2. In Text type the text for the parameter to be displayed in the report viewer as a prompt to the end user. If not set, the Name of the parameter will be used instead.
3. In Type, select the data type for the parameter value. By default String type is selected.
4. You can leave the Value property blank, enter a literal value, or click the ellipses to invoke the Expression Edit Dialog.
5. If the parameter can contain a blank value, set AllowBlank accordingly.
6. If the parameter can contain a null value, set AllowNull accordingly.
7. To allow a user to select more than one value for the parameter, set MultiValue accordingly.
8. To allow a user to select or change a parameter value, set Visible to True.

Defining AvailableValues for ReportParameter’s UI using Report Designer

Expand the AvailableValues property of the report parameter and fill in the following settings to determine the values the end user can choose from.

• Set the DataSource property to specify the data source from which the available values of the editor will be loaded. The same object types used as data sources for the report can be used as data sources for the report parameters. If no DataSource is specified, available values are not loaded.
• In the ValueMember property choose a column from the data source from which the editor to load the values.
• In the DisplayMember property choose a column from the data source from which the editor to draw the value labels.
• In the Filters you can limit the number of records in the available values based on specified filter rules. If the conditions of the rules are met the record is included. Filters are defined using the Edit Filter Dialog.
• Sorting can be performed on the available values through the Sorting property. Sorting controls the order of the items provided to the user to choose from. Sorting is defined using the Edit Sorting Dialog.

Add a Report Parameter programmatically

Telerik.Reporting.ReportParameter reportParameter1 = new Telerik.Reporting.ReportParameter();
reportParameter1.Name = "Parameter1";
reportParameter1.Text = "Enter Value for Parameter1";
reportParameter1.Type = Telerik.Reporting.ReportParameterType.Integer;
reportParameter1.AllowBlank = false;
reportParameter1.AllowNull = false;
reportParameter1.Value = "=10";
reportParameter1.Visible = true;
report1.ReportParameters.Add(reportParameter1);

Dim reportParameter1 As New Telerik.Reporting.ReportParameter()
reportParameter1.Name = "Parameter1"
reportParameter1.Text = "Enter Value for Parameter1"
reportParameter1.Type = Telerik.Reporting.ReportParameterType.Integer
reportParameter1.AllowBlank = False
reportParameter1.AllowNull = False
reportParameter1.Value = "=10"
reportParameter1.Visible = True
report1.ReportParameters.Add(reportParameter1)

Defining AvailableValues for ReportParameter’s UI programmatically

reportParameter1.AvailableValues.DataSource = objectDataSource1;
reportParameter1.AvailableValues.ValueMember = "= Fields.EmployeeID";
reportParameter1.AvailableValues.DisplayMember = "= Fields.FirstName";
Telerik.Reporting.Filter filter1 = new Telerik.Reporting.Filter();
filter1.Expression = "=Fields.ProductCategory";
filter1.Operator = Telerik.Reporting.FilterOperator.Equal;
filter1.Value = "=Parameters.ProductCategory";
reportParameter1.AvailableValues.Filters.AddRange(new Telerik.Reporting.Filter[] { filter1 });
Telerik.Reporting.Sorting sorting1 = new Telerik.Reporting.Sorting();
sorting1.Expression = "=Fields.ProductSubcategory";
sorting1.Direction = Telerik.Reporting.SortDirection.Asc;
reportParameter1.AvailableValues.Sortings.AddRange(new Telerik.Reporting.Sorting[] { sorting1 });

reportParameter1.AvailableValues.DataSource = objectDataSource1
reportParameter1.AvailableValues.ValueMember = "= Fields.EmployeeID"
reportParameter1.AvailableValues.DisplayMember = "= Fields.FirstName"
Dim filter1 As New Telerik.Reporting.Filter()
filter1.Expression = "=Fields.ProductCategory"
filter1.Operator = Telerik.Reporting.FilterOperator.Equal
filter1.Value = "=Parameters.ProductCategory"
reportParameter1.AvailableValues.Filters.AddRange(New Telerik.Reporting.Filter() {filter1})
Dim sorting1 As New Telerik.Reporting.Sorting()
sorting1.Expression = "=Fields.ProductSubcategory"
sorting1.Direction = Telerik.Reporting.SortDirection.Asc
reportParameter1.AvailableValues.Sortings.AddRange(New Telerik.Reporting.Sorting() {sorting1})

In the above snippet, the Expressions =Fields.[Field Name] reference fields from the data source of the report parameter, i.e. from its AvailableValues.DataSource. The applied filter will limit the parameter AvailableValues only to the data rows that have the same =Fields.ProductCategory value as the one specified by the other Report Parameter =Parameters.ProductCategory. After the filtering, the values in the AvailableValues will be sorted based on the field specified as an Expression for the sorting and its Direction, i.e. =Fields.ProductSubcategory, in ascending order.