Reporting - Parameter Enhancements (v18.2)

The Report Parameter feature is crucial to almost any report. It is the main mechanism available to end-users to control report output, using parameters for filtering, sorting or even dynamic grouping of data. This post describes some new functionality we brought to Report Parameters in v18.2.

Allow Null Input

Report Parameters now allow you to select a null value. Of course it is up to your data retrieval logic how this value is interpreted. Here is an example of a stored procedure that returns either a filtered or a complete result set depending on the parameter value passed in:

CREATE PROCEDURE GetOrders
  @OrderId int = null
AS
BEGIN
  SET NOCOUNT ON;
  SELECT * FROM Orders WHERE
    (@OrderId IS NULL OR Orders.OrderID = @OrderId)
END

While creating a report in the data source wizard or creating a new parameter in the designer, enable the Parameter.AllowNull property:

If you clear the Value property of the report parameter, its default value will be null.

At runtime, a (none) item is now included in the drop-down editor for the report parameter:

For parameter editors without a drop-down, you can just delete the value or click the cross button in Web Document Viewer parameter editors:

Look-Up Parameter Sorting

This new feature allows you to sort look-up values displayed in the drop-down of a report parameter. By default, these values are displayed in the order defined by the data source, e.g. by an ORDER BY clause in SQL. Now you can configure the SortOrder and SortMember properties to set up sorting independently of the data source . You can even sort by members that are not used as DisplayMember or ValueMember:

“All selected” Text For The Multi-Value Parameter Editor

This user interface enhancement clearly shows when all available values in a list are selected. The text All selected (<count>) is displayed in this case:

If you include selected parameter values in a report and you’d like to easily display a similar All Values Selected state information in a label, here’s a custom expression binding function implementation that does this:

public class Parameter_AllSelectedFunction : ICustomFunctionOperatorBrowsable {
  public int MinOperandCount => 2;
  public int MaxOperandCount => 2;
  public string Description => "Parameter_AllSelected(XtraReport report, string parameterName) \r\n Checks if all items are selected for a multi-value parameter and returns an indicative string value";
  public FunctionCategory Category => FunctionCategory.All;
  public string Name => "Parameter_AllSelected";

  public object Evaluate(params object[] operands) {
    XtraReport report = operands[0] as XtraReport;
    Parameter p = (report).Parameters[(operands[1].ToString())];
    if (p.MultiValue == false || p.LookUpSettings == null)
      return "Not a multi-value parameter";
    LookUpValueCollection col = LookUpHelper.GetLookUpValues(
      p.LookUpSettings, new XRDataContext());
    if (col.Count == (p.Value as Array).Length)
      return "All Values Are Selected";
    else if ((p.Value as Array).Length == 0)
      return "No Values Are Selected";
    return p.Value;
  }

  public bool IsValidOperandCount(int count) => count == 2;

  public bool IsValidOperandType(int operandIndex,
    int operandCount, Type type) =>
      (operandIndex == 0 && typeof(XtraReport).IsAssignableFrom(type)) ||
      (operandIndex == 1 && type == typeof(string));

  public Type ResultType(params Type[] operands) => typeof(string);
}

Register this function in your app as described in the CustomFunctions help topic, and then use it in an expression binding:

Parameter_AllSelected([ReportItems].[Report], 'Categories')

We are considering for the future to provide a feature that selects all parameter values by default, both for static and dynamic lists. What are your thoughts on this?

A Parameter.Tag Property

We introduced this enhancement in the minor v18.2.5 update. As usual, the Tag property enables you to store extra information together with a standard object, in this case the Parameter. There had been a few requests for this functionality, targeting scenarios where end users create report parameters in the designer. Using the Tag property, these parameters can carry information that is evaluated in event handlers like CustomizeParameterEditors and ParametersRequestBeforeShow, or in a custom implementation of the ParameterTemplateSelector class.

Bonus Feature: Support For A “?” Prefix In Expression Bindings

This is for the convenience of the report developer: to easily include a report parameter in an expression, simply type a ? (question mark) and then pick the parameter from the popup list. This replicates the behavior of the old FilterString property editor and makes working with parameters in the Expression editor just as simple!

Your Thoughts Count

Please feel free to let us know what you think by leaving a comment or opening a Support Center ticket. Your reply to this short survey would also be much appreciated:

For future releases, we plan further enhancements to the Report Parameter feature set. We will talk more about this at a later point, but we’d like to hear from you if you have report parameter scenarios that currently require custom coding.