Report parameters are defined when a report is created, and users can set their values in the preview.
Parameters can be strings, dates, integers, booleans or other types
and multiple methods are supported to enter them, including selection from static and dynamic lists.
A report developer can use parameter values to construct expressions
for example to retrieve or process data on the basis of user-supplied input.
From a developer's perspective, one challenge associated with report parameters is to cover all possible value combinations
including optional parameters.
The following demo illustrates the best practices.
I begin this demo with a report that shows sample order data loaded from a JSON file.
The top-level orders include date information
and the first report parameter I create will enable filtering for orders after a date specified by the user.
In the Field List, I right-click the empty node Parameters and I choose Add Parameter from the context menu.
In the dialog, you can see that parameters support many options, and I will address each one of them in turn.
First, I enter the name OrdersOnOrAfter - no spaces here, since this is the technical name of the element I'm creating.
In the Description field, I enter the same term with spaces, since this is what the user will see as a parameter name.
Now I open the combo box with the supported parameter types.
Various types of numbers are included, as well as strings, boolean values and Guid IDs. I choose Date for this demo.
For now I don't need to change any other settings in the dialog and I click OK to close it.
The new parameter appears in the Field List, and the Properties window displays its settings.
The context menu includes an Edit Parameters item, which displays all parameters in one dialog for easy access to their properties
and the dialog uses the same entry fields you just saw when I created the parameter.
This can be useful to change parameters later, or to work with many parameters efficiently.
The dialog allows you to change the order of parameters in the preview panel.
I switch to the Report Explorer now and select the report itself.
Then I bring up the editor for its FilterString property.
I will use the parameters in this demo for filtering purposes.
Note that parameters can be used in other ways and you will hear more about these use cases in future videos.
I want to configure a criterion for this report that selects data with an order date greater or equal to the parameter value provided by the user.
I click the Plus symbol to add an item to the filter, and then I select Add Condition.
I choose date as the fieldname for the condition
And I change the comparison operator to Is greater than or equal to.
Now I need to enter the parameter name as the value to compare to, and this requires a little trick in the UI
I click the small icon next to the entry field. On the first click the field changes to accept field names
and on a second click it changes to display parameters.
Since the parameter I created is the only one in the report so far, it is preselected.
Note that the small icon is now a question mark
and the filter preview also uses a question mark as the prefix for the parameter name.
Whenever parameters are referred to in expressions, the syntax with the question mark prefix is used.
As an alternative approach to the editing UI I just demonstrated, it is also possible to use a custom expression.
Some developers find this more convenient, so I will show this approach as well.
I add another criterion to the filter, and this time I choose "custom expression".
The Expression Editor appears, and fields as well as parameters are available in the selection lists in the lower part of the window.
I can also enter an expression directly, so I add the text for the demo criterion, using the same syntax you just saw in the Filter Editor.
I leave the dialog, and the filter now includes the same criterion twice - only the display is slightly different
because one item is a condition element and the other a custom expression.
To complete this part of the demo, I confirm the filter now, and then I bring the dialog back up from the Properties window.
Since both parts of the filter represent the same criterion, the editor now displays them both in the same format.
You see that you have a free choice to use either approach when creating filters, and the outcome will be the same.
And here's a final hint: you can even edit the filter string directly in the lower panel of the FilterString Editor dialog.
I remove one of the duplicate entries now and confirm the dialog again.
The report is ready to view now.
I switch to the Preview, and you can see that the behavior has changed compared to the first time I activated it.
The preview now waits for the user to submit parameter values before it displays the report.
I click Submit and the report renders, but it is empty - none of the sample data rows has an order date after today.
I change the date to January 1st, and now the report displays six pages of data.
I change the date again, this time to the first of April
And the report renders on three pages
Without checking the details precisely, it appears that the filter does its job.
At this point, the parameter is mandatory.
Technically, this is true in two different ways: the data type means that a value must always be entered
and the preview automatically waits for the user to supply the parameter before it renders the report.
Both aspects can be changed, and I begin to do this by setting the property AllowNull to True on the parameter.
In the preview again, there is one difference now: the date editor displays a Clear button at the bottom
which allows me to remove the value.
I can then submit the parameter, even though no value is given, and the report renders the complete set of sample data.
This result is very good, but unfortunately it is misleading.
I bring up the FilterString Editor to remind myself of the condition:
it compares the date field to the parameter, using a "greater or equal" operator.
As it happens, this same operator will always return true if the parameter should be null.
But this is pure coincidence.
I'll demonstrate this to you by changing the parameter to "less or equal".
Back in the preview, the report data is limited by the parameter.
However, now I take the same step as before and clear the parameter.
This time the report renders without any data, instead of displaying all data like before.
This happens because the comparison with the null value now returns false in all cases.
Keep this in mind: if you allow null values for parameters
you must write expressions and other parameter-dependent logic in such a way that the null values are taken into account explicitly.
I edit the filter string, and the first step is to change the top-level logical operator to Or.
Then I add a custom expression to check for the null value.
I change the operator back to "greater or equal", and now the filter is set up correctly to take null values into account
rows will be included if either the parameter is null, or if the date is greater than the parameter value.
One more test in the preview shows that the behavior works correctly.
To get back to the original goal of making the parameter optional, there's one more useful change for null value support
I reset the Value property, so that no initial value is set for the parameter.
What remains is the behavior of the preview, and to prevent it from waiting for parameters, I need to change a property on the report itself.
I select the report and set its property RequestParameters to False.
I bring up the preview again, and now the report renders immediately, showing all data
The parameter is optional, but it still works as before if I change it to a date.
A final note on parameter initialization: in addition to the Value, there is also a ValueExpression.
You can use this to calculate the value a parameter should have when the preview is first displayed.
As an example, I bring up the Expression Editor and enter a short expression that calculates a date three months before today.
In the preview again, this calculated date becomes the new default value for the parameter
And the report still renders immediately as before.
Now it is time to introduce a second parameter.
This time I will filter for individual customers
And I call the parameter FilterCustomer to distinguish it from the existing field called customer.
Technically, parameters and fields can have the same names, since they use different syntax in expressions.
However, for readability I recommend avoiding overlap.
The description for the new parameter will be "Customer", and I select "String" as the type.
Note that in a real application, you would probably use an ID for a similar use case
but in the demo data the customer field is simply a string with the name.
Like before, I choose to allow null values for the parameter, so that it becomes optional.
The interesting part of the configuration for this parameter is the value source
this time I will enable a combo box that displays values for the user to choose from.
Two different types of value sources are available for the string type, a static and a dynamic type.
The static type is useful if you have a fixed list of values to choose from, while the dynamic type fetches the options from a datasource.
I select DynamicListLookUpSettings for this demo.
As you can see, the setup of the dynamic source includes a full complement of properties for a lookup datasource.
For this demo I select the existing JSON datasource to read the values from
But keep in mind that this source could be completely independent
And you can use the DataMember as necessary to refer to nested elements in combined sources.
The ValueMember is the datasource field that delivers the underlying value for the parameter.
For a lookup this would often be an ID, as I mentioned before, but in this demo case it's the field customer.
The DisplayMember is the field that is displayed in the UI
And I don't need it for the demo because the value can be displayed directly.
To complete my setup I select customer for the SortMember, and I set the SortOrder to Ascending.
Note that the FilterString on this level filters the datasource for the lookup.
This is particularly interesting in some advanced cases where you would like to provide cascading lookups
the filter for one parameter can access a second parameter as a reference.
I confirm the new parameter and switch to the preview page again to test it.
The Customer parameter is included in the panel now
and the combo box lists all the customer names in the datasource, in alphabetical order.
To complete this feature, I need to extend the report FilterString to include the new parameter.
Of course I need to take possible null values into account like before.
For simplicity, I replace the old expression with a new one in the editing panel
and you can see in the top panel how the conditions are combined.
In the preview, I can now select values for any combination of parameters, and they change the filter as expected.
And that’s it for Part 1, Click the link here to continue on with Part 2, or watch other Reporting videos from our playlist.
Don’t forget to subscribe and ring the bell so you get notified anytime we release new content.
Thanks for watching and thank you for choosing DevExpress