Parameters Overview

• Oct 31, 2018
• 4 minutes to read

This document describes possible scenarios of using report parameters and explains how to create parameters at design time. The last section of this document provides links to tutorials that demonstrate the use of report parameters for solving various tasks.

Tip

You can watch the tutorial on the DevExpress YouTube Channel: DevExpress Reporting Parameters

Using Parameters

You can use report parameters to pass data to a report before it has been published. Parameter values can be specified by end-users in a Print Preview or silently assigned in code.

Report parameters can be used to solve the following tasks.

• Filtering

  When filtering report data, parameters can be used for providing values to a report’s XtraReportBase.FilterString.

  

  When filtering data at the level of a data source, you can link report parameter to query parameters that are used in the SELECT statement of a SQL string.

• Calculated Fields

  Parameters can be used as part of a calculated field‘s expression. To refer to a report parameter, use a question mark (?) before its name.

  

• Conditional Formatting

  A formatting rule‘s condition can also reference report parameters.

  

  For a related tutorial, see Limit the Number of Records per Page.

• Data Binding

  You can bind a report control to a parameter and display its value in the report. To create a new label bound to a parameter, drag the parameter from the Field List and drop it onto the required band.

  

  When using mail merge, you can refer to a parameter by adding a question mark before its name.

  

• Dynamic Report Layout

  You can use parameters to select which table columns are displayed in a report.

  For a code sample, see the following example online: How to use XtraReport’s multi-value parameter as a column chooser.

• Scripting

  When processing report data in scripts, you can access a specific parameter in the XtraReport.Parameters collection by its name.

  C#

  private void OnBeforePrint(object sender, System.Drawing.Printing.PrintEventArgs e) {
      xrLabel1.Text = "User: " + XtraReport1.Parameters["param1"].Value;
  }
  

  VB.NET

  Private Sub OnBeforePrint(ByVal sender As Object, ByVal e As System.Drawing.Printing.PrintEventArgs)
     XRLabel1.Text = "User: " + XtraReport1.Parameters("param1").Value
  End Sub
  

Creating Parameters

To create a report parameter at design time, switch to the Field List, right-click the Parameters node and click Add Parameter in the context menu.

This invokes the Add New Parameter dialog where you can customize the created parameter.

This dialog provides the following options.

• Parameter.Name - specifies the unique name by which the parameter can be referred to.
• Parameter.Description - specifies the text that will be displayed in a Print Preview along with the corresponding value editor.

• Parameter.Type - specifies the parameter’s value type, according to which an appropriate value editor is displayed in a Print Preview.

  This property can be set to any standard data type matching the expected data type of the parameter value. To learn how to use parameters of other types, see Create Custom Report Parameters.

• Default value - specifies the default Parameter.Value.
• Show in the parameters panel (corresponds to the Parameter.Visible property) - enable this option to request the parameter value in a Print Preview. Otherwise, the default parameter value is silently passed to the report.

• Supports the collection of standard values - you can enable this option if the parameter is visible (i.e., its value is to be requested in a Print Preview). In this case, an end-user will be requested to choose a value from a predefined list. You can either manually populate this list with possible values, or specify a data source from where these values will be obtained.

  • Dynamic values

    On this tab, you can specify a data source, data adapter (if required) and data member storing parameter values. The value member defines a data field that will provide values to the parameter. The display member defines a data field storing values displayed in a Print Preview.

    

    The value type of the specified data member should match the specified Parameter.Type.

    You can filter the list of values by specifying the LookUpSettings.FilterString property. Using this property, you can implement cascading parameters.

    You can sort the list of values by specifying the LookUpSettings.SortOrder and LookUpSettings.SortMember properties.

    For a code example, see How to assign a list of dynamic values to a report parameter.

  • Static values

    Switch to this tab to specify a static list of possible values. Each value should have a description that is displayed in a Print Preview.

    

    For a code example, see How to assign a list of static values to a report parameter.

• Allow multiple values (corresponds to the Parameter.MultiValue property) - when this option is enabled, a parameter can be assigned a collection of values.
• Allow null value (corresponds to the Parameter.AllowNull property) - indicates whether the parameter’s value can be unspecified.