Range Report Parameters
- 9 minutes to read
This topic describes how to create date range and time range parameters and filter a report’s data by the specified date or time values.
A date range parameter’s editor on Print Preview
The report’s data filtered by the specified date range
A time range parameter’s editor on Print Preview
#Create a Range Parameter in the Report Designer
Follow the steps below to add a range parameter to a report in Visual Studio Report Designer:
- Create a report parameter.
In the Add New Parameter dialog, specify parameter options:
- Parameter type: Date and Time, Date, or Time
- Value Source: Range Parameters
The Start Parameter and End Parameter sections that appear allow you to configure options to create a date or time range:
You can change the Name and initial static Value for the Start Parameter and End Parameter. To specify an expression instead of a static value, click the Value option’s ellipsis button and use the Expression Editor dialog:
Reference the created range parameter. You can reference this parameter in the report’s filter string, in expressions, and in a control’s
Textproperty. You can also bind control and data source parameters to report parameters.We recommend that you use the following functions with range parameters in expressions and filter strings:
- InDateRange(Date, FromDate, ToDate) - equivalent to the
FromDate <= Date && Value < Dateexpression. - InTimeRange(Time, FromTime, ToTime) - equivalent to the
FromTime <= Time && Time < ToTimeexpression (including cases where the range spans midnight, such as 23:00-01:00). - OutOfTimeRange(Time, FromTime, ToTime) - equivalent to the
FromTime > Time || Time => ToTimeexpression (including cases where the range spans midnight, such as 23:00-01:00).
The image below filters the report’s data by the following filter string:
InDateRange([ShippedDate], ?paramDateRange_Start, ?paramDateRange_End)
- InDateRange(Date, FromDate, ToDate) - equivalent to the
When you switch to the report’s Print Preview tab, the Parameters Panel displays the newly created range parameter. Click the editor to set a range. The editor type depends on the parameter type:
- An editor for “Date” and “Date and Time” range parameters:
- An editor for “Time” range parameters
After you submit start and end values, the report document shows filtered data. The report below shows the ShippedDate field filtered by the date range parameter:
#Create a Range Parameter in Code
- Initialize a RangeParametersSettings class instance and set up its properties.
- Create a parameter and set its Type to a DateTime, DateOnly, or TimeOnly value.
- Assign the created
RangeParametersSettingsobject to the parameter’s ValueSourceSettings property. - Add the parameter to the report’s Parameters collection.
The following code sample creates a date range parameter in code and uses this parameter to filter the report’s data:
using System;
using System.IO;
using DevExpress.DataAccess.ConnectionParameters;
using DevExpress.DataAccess.Sql;
using DevExpress.XtraReports.Expressions;
using DevExpress.XtraReports.Parameters;
using DevExpress.XtraReports.UI;
// ...
// Create a date range parameter.
var dateRangeParam = new Parameter();
dateRangeParam.Name = "dateRange";
dateRangeParam.Description = "Date Range:";
dateRangeParam.Type = typeof(System.DateTime);
// Create a RangeParametersSettings instance and set up its properties.
var dateRangeSettings = new RangeParametersSettings();
// Specify the start date and end date parameters.
dateRangeSettings.StartParameter.Name = "dateRangeStart";
dateRangeSettings.StartParameter.ExpressionBindings.Add(
new BasicExpressionBinding("Value", "AddYears(Today(), -1)")
);
dateRangeSettings.EndParameter.Name = "dateRangeEnd";
dateRangeSettings.EndParameter.ExpressionBindings.Add(
new BasicExpressionBinding("Value", "AddYears(Today(), 0)")
);
// Assign the settings to the parameter's ValueSourceSettings property.
dateRangeParam.ValueSourceSettings = dateRangeSettings;
// Create a report instance and add the parameter to the report's Parameters collection.
var report = new XtraReport1();
report.Parameters.Add(dateRangeParam);
// Use the parameter to filter the report's data.
report.FilterString = "GetDate([UpdatedOrderDate]) Between(?dateRangeStart,?dateRangeEnd)";
#Customize Predefined Ranges
Web Report controls do not support DateOnly and TimeOnly range parameters. You can only create a range parameter of DateTime type.
The date and time range parameter editor allows you to select a range from a list of predefined ranges. You can remove items from the list or add a custom range.
#WinForms and WPF Reporting
The set of predefined date ranges is stored in the RangeParameterEditorOptions static class and is available in all date range parameter editors when they are displayed in the Preview tab. Use the RegisterDateRange(String, Func<DateTime>, Func<DateTime>) to add a new predefined date range to the collection.
The following code sample removes all predefined date ranges and creates two new ranges:
using DevExpress.XtraReports.Parameters;
using DevExpress.XtraReports.Expressions;
// ...
// Remove all predefined ranges and add two new date ranges.
RangeParameterEditorOptions.PredefinedDateRanges.Clear();
RangeParameterEditorOptions.RegisterDateRange("September", () => new DateTime(2019,9,1), () => new DateTime(2019,9,30));
RangeParameterEditorOptions.RegisterDateRange("October", () => new DateTime(2019,10,1), () => new DateTime(2019,10,31));
If you want to customize time ranges, use the RangeParameterEditorOptions.RegisterTimeRange methods to add a new predefined time range to the collection.
The following code adds two new time ranges to the existing collection:
using DevExpress.XtraReports.Parameters;
// ...
// Uncomment the line below if you want to clear the collection before adding new time ranges:
//RangeParameterEditorOptions.PredefinedTimeRanges.Clear();
string timeRangeNightShift = "Night Shift";
if (!RangeParameterEditorOptions.PredefinedTimeRanges.ContainsKey(timeRangeNightShift)) {
RangeParameterEditorOptions.RegisterTimeRange(timeRangeNightShift,() => new TimeOnly(23,0),() => new TimeOnly(5,0),SvgImage.FromFile("time.svg"));
}
string timeRangeLastTwoHours = "Last Two Hours";
if (!RangeParameterEditorOptions.PredefinedTimeRanges.ContainsKey(timeRangeLastTwoHours)) {
TimeOnly previousHour = TimeOnly.FromDateTime(DateTime.Now.AddHours(-2));
TimeOnly currentHour = TimeOnly.FromDateTime(DateTime.Now.AddHours(0));
RangeParameterEditorOptions.RegisterTimeRange(timeRangeLastTwoHours, () => previousHour,() => currentHour);
}
#Web Reporting
Warning
Web Report controls do not support Date
Only and TimeOnly range parameters. You can only create a range parameter of DateTime type.- The Native Report Viewer for Blazor does not display support predefined date ranges for date range report parameters.
Predefined date ranges are stored in the client-side collection of the Document Viewer widgets. The set of predefined date ranges is available in all date range parameter editors when they are displayed in the Preview tab.
The following code removes built-in predefined ranges and adds two custom predefined ranges.
<script type="text/javascript" id="script">
function CustomizePredefinedRanges(s, e) {
DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.splice(0,
DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.length);
DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
displayName: 'September',
range: () => [
new Date(2023, 8, 1),
new Date(2023, 8, 30)
]
})
DevExpress.Reporting.Viewer.Widgets.predefinedDateRanges.push({
displayName: 'October',
range: () => [
new Date(2023, 9, 1),
new Date(2023, 9, 31)
]
})
}
</script>
<dx:ASPxWebDocumentViewer ClientInstanceName="WebDocumentViewer1" ID="ASPxWebDocumentViewer1" runat="server">
<ClientSideEvents BeforeRender ="CustomizePredefinedRanges" />
</dx:ASPxWebDocumentViewer>
#Limitations
Web Report controls do not support DateOnly and TimeOnly range parameters. You can only create a range parameter of DateTime type.
- The Native Report Viewer for Blazor does not support predefined date ranges.