Parameters Overview

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.

    parameters-filter-string-multi-value

    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.

    parameters-expression-calculated-field

  • Conditional Formatting

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

    parameters-formatting-rule-condition

    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.

    ReportParameters4a

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

    MailMerge_Parameters

  • 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.

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

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.

Shared_FieldList_AddParameter

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

parameters-add-new-dialog

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.

  • 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.