In the first video about report parameters, I demonstrated two different parameters and several report filtering scenarios.
The following demo continues with the same sample project.
In the Field List you can see the two parameters I created previously.
I switch to the Preview and the report is displayed for the three months prior to the current date.
I can change the starting date in the parameter panel
And I can limit the data to a specific customer by selecting from the combo box.
I want to introduce two more filtering parameters in this demo
and increase the complexity to mirror a real-world application more closely.
After that, I will add a scenario that uses parameters to dynamically apply formatting to values
and I will also validate user-supplied parameters.
The first new filtering parameter is an alternative to the existing customer selection.
Instead of selecting a single customer from a list
users will be allowed to enter a substring and see all the customers included in the output that match the string.
I add a parameter and call it CustomerSubstring.
The type is String
And null values are allowed.
To accommodate the new parameter in the filter string, I insert a complex expression.
It is structured so that a specific selected customer entry is prioritized over the substring search
but the date range is always applied in addition, if it is given.
I quickly demonstrate the new parameter in the preview.
First, the date range is obviously still applied.
When I select a specific customer item, the report filters accordingly.
If I enter a substring additionally - I go for a single "X" - this is ignored and the report does not change.
But when I remove the specific selection, the search string is applied
I enter an "A" as a starting point and limit things more from there to make it obvious that the substring filter also works correctly.
Moving on to the second new filtering parameter, this will be an improved version of the OrdersOnOrAfter date parameter.
Once again I add new parameter and this time I call it DateRange.
I select the type Date and then I open the combo box for the value source.
The RangeParameterSettings are new in the list, since they apply only to the Date type.
This special settings object has some useful extra functionality
and it is also an example of an extensibility point which you can use yourself for advanced scenarios.
The date range system is even extensible in itself, so that custom ranges can be added.
I configure the "start" and "end" parts of the parameter with their own value expressions to initialize them.
The start of the range will be three months in the past like before, while the end will be the current date.
I confirm the new parameter and bring up the Edit Parameters dialog.
I move the DateRange parameter to the top of the list.
For this demo, I leave the old OrdersOnOrAfter parameter in the list, even though it won't be used anymore.
I click OK to confirm the new order
And I edit the report filter string again.
This time the filter I insert takes the complete range into account
using a "greater or equal" operator with the range start and a "smaller or equal" operator with the range end.
In the preview I test the new range support.
When I select a date range from the list on the left side of the popup, the calendar controls are populated accordingly.
At the same time, I can still select any custom range by defining the start and end dates individually.
As a final example for report parameter use cases, I will introduce a different scenario now.
I will highlight data on the basis of parameters, and validate parameter values to make sure they are in a sensible range.
I begin by adding two new parameters.
One of them is called LinePriceLowThreshold
And I use a decimal type.
As before, I allow null values, and I make sure that the parameter value is not defined by default.
The second parameter is configured the same way, with the name LinePriceHighThreshold.
As you can see, there are two new placeholder labels in the report
These can serve as a legend for the highlighting mechanism, displaying the background colors I will use
as well as the actual parameter value configured by the user.
Before I set up these legend labels, I select the cell that displays the line price
and I add an expression for the BackColor property.
The expression colors the cell according to the threshold values, taking into account that the parameters are optional.
A quick test in the preview confirms that this works correctly for threshold values like 100 and 1000.
Back to the legend labels, and I want to address the topic of validation before I move on.
The expression I'm using now checks whether the two parameter values are provided before using them.
However, in reality it makes sense to also perform sanity checks on the values a user submitted
instead of applying them blindly.
For example, none of the threshold values should be negative, and there could be certain ranges the values should be limited to.
The problem is that I need this validity information both for the highlighting expression itself, and for the labels.
I create two additional parameters, using Boolean types, which will relay the validity information for the bound expressions.
I deactivate the option to display these parameters in the panel, since they will be used automatically behind the scenes.
Now I create an event handler for BeforePrint on the report level.
I add some code which fetch the values of the user-defined parameters
checks for null, and also takes a range of valid values into account
the latter part is just an example for some real-world business-specific validity test.
Eventually the two extra parameters are configured to indicate whether the threshold values can be used further
in report expressions.
I change the BackColor expression first.
It can now take advantage of the new parameters, so that any validation logic doesn't need to be duplicated.
Now I can finally set up the legend labels.
I use two expressions for each label, one for the background color and one for the text.
I return simple placeholders if the respective thresholds are not configured, or are invalid
But of course you can be as detailed or verbose as you like in a scenario like this.
You could even hide the legend labels if they are not needed, by using an expression for the Visible property.
Before I switch to the preview, I need to build the project since I have added code to the report.
The preview comes up with the placeholder labels, because no highlight thresholds are established by default.
I enter a value for the low threshold and submit
then I add a high value and submit again
And the labels update correctly.
Finally, I change one of the values to make it negative, and the labels update correctly again.
This concludes the parameter demos.
Note that parameters can be utilized in conjunction with many report features
in addition to the filtering and highlighting examples you have seen.
And that’s it for the second part of our reporting demo, If you haven’t watched the first part, you can click the link here
or watch other reporting videos from our playlist.
Don’t forget to subscribe to our channel and ring the bell so you get notified anytime we release new content.
Thanks for watching and thank you for choosing DevExpress