Reporting

In Telerik Reporting, parameters are used to specify the data to use in a report, connect related reports together, and vary report presentation. To design a report that uses parameters effectively, you must understand how parameters and Data Source components work together, how parameters and expressions work together and how parameters can be managed. What you choose to parameterize can influence the report design and layout.

After a report parameter is created, you can modify the default values and other parameter properties, such as visibility. For example, you might want to create a report with a hidden parameter that selects data specific to the user running the report. Parameters can contain single values or multiple values, use a static or query-based valid values list, and accept null or blank values. Multivalue parameters enable users to select more than one value at run time.

The major usages of the report parameters are:

  • to vary report data retrieved from a Data Source component

  • in expressions to directly provide a value

  • in data item filtering, sorting or grouping criteria

Report Parameter Properties

  • Type

    Determines the type of the values that are acceptable. The allowed types are Boolean, DateTime, Integer, Float, String. Acceptable values for each type are listed here: ReportParameterType The default parameter type is String.

  • Name

    Specifies the parameter name and used to access the parameter. The name must be a valid identifier - may contain only digits (0-9), letters (a-z, A-Z), and underscore sign (_). Must begin with a letter or underscore.

  • Value

    Used to specify value for the parameter. It can be blank, value of the allowed types, an Expression that evaluates to an object, or IEnumerable containing values of the allowed types.

    Note

    When a parameter accepts multiple values (MultiValue=True), you can set the value by programmatically assigning an IEnumerable of the allowed types.

  • Text

    Specifies the text for the parameter to be displayed in the report viewer as prompt to the end user. It can be blank, string or Expression. If not set, the Name of the parameter will be used instead.

  • Visible

    Specifies whether the editor will have UI in the parameters area. When at least one report parameter has the Visible property turned on, a parameter area is shown as part of the report viewer.

  • AllowNull

    Determines if null (Nothing in VB.Net) value is acceptable.

  • AllowBlank

    Applied only when the parameter is of type String. Determines if an empty string is acceptable.

  • MultiValue

    Determines if a collection of values (of the specified Type) is acceptable as value of the parameter. Parameters with MultiValue turned on are mainly used with the IN logical operator.

  • AvailableValues

    The available values, or valid values, are a set of predefined values which are acceptable as value of the parameter. Each available value may have label that will be displayed if the parameter is visible. To define available values for a parameter you need to setup the following nested properties:

    DataSource – a data source for the value/label pairs. Same data sources are supported as for the Data Items, including the Telerik Reporting Data Source Components.

    ValueMember – a column name, expression, or embedded expression based on the DataSource schema. It is used as value in the value/label pair.

    DisplayMember – a column name, expression, or embedded expression based on the DataSource schema. It is used as label in the value/label pair. If omitted the ValueMember will be used as DisplayMember as well. Optional.

    At design time, you can use the Data Source Wizard to select an existing or to create a new data source.

  • Mergeable

    Controls parameter merging in ReportBook. The default value of the Mergeable property is true. Set the Mergeable property to false if you want to prevent a parameter from being merged with its equivalent ones.

  • AutoRefresh

    Determines whether to trigger the report preview after changing the value for a parameter. Applies only for visible parameters. Default value is False.

Report Parameter Validation

When a report enters in the processing stage, its value is validated against its validation properties. If one or more parameters do not have valid values, processing is aborted. The following properties are used to validate the supplied parameter’s value:

  • Type

  • AllowNull

  • AllowBlank

  • MultiValue

  • AvailableValues

Passing a value to Report Parameter

A Parameter is populated by setting its Value property. You may set this property to a valid value or an expression that evaluates to a valid value. The expression evaluation and validation are performed while the report is processed. An expression used as parameter value may not contain reference to the built-in Fields collection, as fields are still not populated when the parameters are processed.

Report Parameters' value can be populated in one of the following ways:

  • At design time through the ReportParameter Collection editor.
  • Using the automatic user interface that each Report Viewer provides.
  • Programmatically by using the ReportParameters collection.
  • Using a SubReports  Parameters collection.

Cascading (dependent) parameters

Cascading parameters provide a way of creating dependencies between parameters to handle large amounts of input data. You can define a set of parameters where the list of available values for one parameter depends on the values chosen in other parameters.

For example, the first parameter could present a list of product categories. When the user selects a category, the second parameter is updated with a list of subcategories within the category. A third parameter could then display a list of products within the selected subcategory. The value for the product parameter is used to filter the report to a particular product. The parameters which values depend on other parameters values are known as cascading, dependent or hierarchical parameters.

Parameter area

When at least one report parameter has its Visible property turned on, a parameter area is shown as part of the report viewer. This helps the report developer to easily provide input method for the end users. Based on the settings of the parameters, a suitable editor UI is created. Parameter layout on the parameter area is formatted automatically. The order is determined by the order that parameters appear in the ReportParameters collection. The end user can enter or select values in the editors. When at least one visible report parameter has AutoRefresh property turned off, a Preview button is available. In this case to preview the report, the end user should click the Preview button. If all parameters have default values, the report runs automatically on first view. You can show or hide the parameters area from the Parameters button in the report viewer’s toolbar.

See Also