Reporting — Parameters Panel Customization (v21.2)

As you may already know, DevExpress Reports v21.2 allows you to customize the appearance of the Parameters panel for both the WinForms and WPF platform. If you are unfamiliar with our Parameters panel, please refer to the following help topic for more information:  The Parameters Panel.

Our new Parameters panel customization API allows you to combine report parameters into expandable groups, place parameters side-by-side, add separators, and more.

Default panel	Customized panel

API Examples

The following code sample customizes the Parameters panel to mimic the screenshot above:

using DevExpress.XtraReports.Parameters;
using Orientation = DevExpress.XtraReports.Parameters.Orientation;

ParameterPanelFluentBuilder.Begin(report)
    .AddGroupItem(g0 => g0
        .WithTitle("Select ship date")
        .AddParameterItem(report.Parameters[0], p0 => p0
            .WithLabelOrientation(Orientation.Vertical)))
    .AddGroupItem(g1 => g1
        .WithTitle("Specify sort options")
        .WithOrientation(Orientation.Horizontal)
        .WithShowExpandButton(true)
        .AddParameterItem(report.Parameters[1], p1 => p1
            .WithLabelOrientation(Orientation.Vertical))
        .AddSeparatorItem()
        .AddParameterItem(report.Parameters[2], p2 => p2
            .WithLabelOrientation(Orientation.Vertical)))
.End();

The primary entry point is the ParameterPanelFluentBuilder static class. This class allows you to call various customization methods sequentially. The Begin method accepts a report whose panel is to be customized (and starts the customization flow,) and the End method ends the process. In between these two methods, you can customize report parameter appearance, create and customize groups, and add separators as requirements dictate.

In the code sample above, the AddGroupItem method adds a visual group to the panel. The method accepts a customization action (to chain various methods to set up the group’s appearance). The AddParameterItem method adds an existing report parameter to the group. This method accepts a parameter object and an action that allows you to modify parameter appearance.

How to Customize the Location of a Parameter Description

You can use the WithLabelOrientation(Orientation orientation) method to specify the location of a parameter’s label relative to the editor.

orientation = Horizontal (Default)	orientation = Vertical

using DevExpress.XtraReports.Parameters;
using Orientation = DevExpress.XtraReports.Parameters.Orientation;

ParameterPanelFluentBuilder.Begin(report)
    .AddParameterItem(report.Parameters[0], p => p
        .WithLabelOrientation(Orientation.Vertical))
.End();

How to Create and Customize a Group of Parameters

The following code sample creates a group and places parameters inside the group side-by-side:

using DevExpress.XtraReports.Parameters;
using Orientation = DevExpress.XtraReports.Parameters.Orientation;

ParameterPanelFluentBuilder.Begin(report)
    .AddGroupItem(g => g
        .AddParameterItem(report.Parameters[0], p0 => p0
            .WithLabelOrientation(Orientation.Vertical))
        .AddParameterItem(report.Parameters[1], p1 => p1
            .WithLabelOrientation(Orientation.Vertical))
        .WithTitle("Specify sort options")
        .WithOrientation(Orientation.Horizontal))
.End();

Default panel	Customized panel with a group

This example uses the WithTitle method to specify a group title and the WithOrientation method to change parameters orientation inside the group. If you want parameters to be displayed side-by-side in the panel but outside the group, hide the group borders. Call the WithBorderVisible(bool borderVisible) method and set its borderVisible argument to false.

borderVisible = true (Default)	borderVisible = false

Other customization methods allow you to hide a group title, add an expand/collapse button, and expand/collapse a group.

WithTitleVisible(bool titleVisible)

titleVisible = true (Default)	titleVisible = false

WithShowExpandButton(bool showExpandButton)

showExpandButton = false (Default)	showExpandButton = true

WithExpanded(bool expanded)

expanded = true (Default)	expanded = false

New Expressions for Enabled and Visible Properties

A couple of other new features of note.

Our Parameters panel includes a new Enabled property (places a parameter editor into a read-only state).

You can also specify an expression for this property to enable/disable the editor based on the value of a different parameter.

You can set this property when you create a report parameter in the Report Designer (Desktop and Web) or in code.

using DevExpress.XtraReports.Parameters;
using DevExpress.XtraReports.Expressions;

report.Parameters["sortOrder"].ExpressionBindings.Add(
    new BasicExpressionBinding() {
        PropertyName = "Enabled",
        Expression = "!IsNullOrEmpty(?sortProductsBy)",
});

In much the same way, you can now assign an expression to the Visible property. This allows you to display/hide the parameter editor based on the value of another parameter.

Note that this functionality does not automatically modify a report's filter string - you have to modify it manually according to the submitted values in the XtraReport.DataSourceDemanded event handler.

Future Plans

Build the Parameters Panel Layout Visually

The customization options described herein must be applied/implemented via our API (in code). For those interested in visual (UI-based) customization, we expect to introduce this option (within the DevExpress Report Designer) in our next update. Once we add this feature, you will be able to customize the panel directly inside the Report Parameters Editor window:

While the screenshot above demonstrates the Parameters panel within a desktop app, we will maintain feature parity between platforms and will add this functionality for Web-centric Reporting components as well.

Use a Control as a Parameter Editor

Current Built-in customization options allow you to substitute default parameter editors with DevExpress edit controls (BaseEdit descendants) when targeting WinForms or DevExtreme editors when targeting the Web. We are also considering ways in which to extend this capability and allow you to use any control (e.g. ListBox) as a parameter editor. 

Your Feedback Matters

We’d love to hear your feedback on this new capability. Does our customization API effectively address your needs? Do you need additional customization options? Feel free to share your thoughts and suggestions below.

Free DevExpress Products - Get Your Copy Today