In this blog post, I’ll review our new Parameters Panel customization editor (v22.1). Before I do, a quick word or two about the Parameters Panel...
The Parameters Panel
The DevExpress Parameters Panel is a UI element that allows you to specify parameter values and dynamically supply data to a given report.
In our previous release (v21.2), we introduced an API (ParameterPanelFluentBuilder class) to customize the appearance of the Parameters Panel itself. Specifically, the API allowed you to combine report parameters into expandable groups, place parameters side-by-side, and add separators as needed.
While the API offered robust customizations options, these capabilities were only available via code.
Parameters Panel Customization UI
v22.1 ships with our new Parameters Panel Customization UI editor – allowing you to customize the panel directly inside the Report Parameters Editor window without writing any code.
Once you create the appropriate parameters for your report, you can open this new editor and apply the same customizations to the panel as those available via our API. The new UI is available in the Visual Studio Report Designer, the DevExpress End-User Report Designer (for WinForms and WPF), and the DevExpress Web End-User Report Designer (for all supported web platforms). All customizations applied to the panel are serialized within a report definition file (REPX).
To show you what’s possible, let's take a quick look at some examples and let’s customize the panel within a WinForms application.
Basics on How to Use the New UI to Customize the Panel
Invoke the Report Parameters Editor
Once you have created the necessary parameters for your report, right-click the Parameters node in the Field List and select Edit Parameters. This action invokes the Report Parameters Editor.
The editor's tree list on the left displays all generated parameters.
Customize Parameters
Select a parameter in the tree list. In the pane on the right (where parameter properties are listed), you can specify how to position the parameter's label relative to the parameter's editor.
The following examples display a panel with two parameters. In the first example (left panel), label orientation for both parameters is set to Horizontal. The second example (right panel) demonstrates the same parameters with label orientation set to Vertical.
In addition to label orientation, you can set the parameter's Visible and Enabled properties to show/hide or enable/disable the parameter's editor. You can specify an expression for these properties to change the parameter's behavior based on specific conditions.
In the example below, the customerName parameter's Enabled property is set to the following expression:
!IsNullOrEmpty(?companyName)This expression ensures that the customerName parameter's editor is enabled only when the companyName parameter has been specified.
You can also change parameter order in the tree list, and in so doing, change parameter order within the Parameters panel. To change parameter order in the tree list, simply use the Up and Down buttons or drag-and-drop parameters within the tree itself.
Create and Customize Groups
Click the Add Group button to create a group.
To change the default group title, select the group and assign a new title to the Title property.
To place parameters inside or outside groups, use the Up and Down buttons or drag-and-drop parameters into the desired group.
Here is an example of a panel that uses groups:
In addition to specifying a group title, you can also customize group appearance with the following properties:
Add Separators
Click the Add Separator button to add a new separator.
Much like parameters, you can use the Up and Down buttons or drag-and-drop operations to place separators inside or outside groups and between parameters.
The following is an example of a Parameters panel with a separator between parameters:
Example: Customize the Parameters Panel in a Web Document Viewer
We've shown you all the basic features available for customization of the Parameters Panel. Now, let's consider a somewhat more advanced example – one in which multiple customization options are combined together.
The images below demonstrate the difference between the default and customized version of the Parameters Panel within the DevExpress Web Document Viewer.
The default panel contains four parameters (the same as those used in our Report Merging demo). The customized panel includes the same parameters: the first two (Sort Categories By and Sort Order) are combined into a group called Specify Sort Settings and placed side-by-side inside the group.
The other two parameters (Chart Appearance and Color Each Bar) are combined into a group called Setup Appearance (with separators between the parameters in both groups).
Once you apply these changes, the list of parameters, groups, and separators will render as follows within the DevExpress Report Designer's Edit Parameters window.
As you’ll hopefully agree, our new Parameters Panel UI editor offers a robust set of customization options – all available from within the Visual Studio Report Designer and the DevExpress End-User Report Designer (for all supported desktop and web platforms).
Your Feedback Matters
Thanks to your feedback/requests, we’ve implemented many new report parameter-related features over the last couple of years. Please take a moment to answer the following two questions: