DateFilterDashboardItem Class

A Date Filter dashboard item that allows end users to filter other dashboard items by date-time values.

Namespace: DevExpress.DashboardCommon

Assembly: DevExpress.Dashboard.v24.1.Core.dll

NuGet Package: DevExpress.Dashboard.Core

Declaration

C#

public class DateFilterDashboardItem :
    DataDashboardItem,
    IDateTimePeriodContext,
    ISupportDateTimePeriods,
    IEditNameProvider

VB.NET

Public Class DateFilterDashboardItem
    Inherits DataDashboardItem
    Implements IDateTimePeriodContext,
               ISupportDateTimePeriods,
               IEditNameProvider

Remarks

The Date Filter allows end users to apply filtering by date to other dashboard items. It displays a set of intervals that allow you to filter out values. You can use the Date Filter as a compact counterpart of the Range Filter dashboard item:

End-users can click the Click to set filter button to invoke the Date Picker:

Run Demo: Date Filter

Create a DateFilter Dashboard Item

To add a new Date Filter to the dashboard, create the DateFilterDashboardItem class instance and add it to the Dashboard.Items collection.

Bind to Data

Use the DateFilterDashboardItem.Dimension property to specify a dimension that provides filter values.

Display Format

To specify the date-time value format, use the dimension’s DateTimeFormat property.

To specify a custom string displayed in the Date Picker component, use the DateFilterDashboardItem.DisplayTextPattern property. You can include placeholders in a custom string. The {0} placeholder is the interval’s start, the {1} placeholder is the interval’s end.

Filter Type

A filter can be a DateTime value, DateTime range or infinite interval before or after a specified date. Use the DateFilterDashboardItem.FilterType property to specify a filter type.

Date Picker

The DateFilter item contains a Date Picker - a button with a drop-down calendar. This button initially displays “Click to set filter”. To change the text, provide the DashboardStringId.DateFilterDatePickerButtonDefaultText localization string or handle the DashboardViewer.DashboardItemControlCreated event and subscribe to the DateFilterControl.CustomDisplayText event.

The Date Picker component can be located at the near end of the Quick Button series, at its far end, or it can be hidden. To change the Date Picker location, use the DateFilterDashboardItem.DatePickerLocation property.

Create Quick Filters

Quick Filters are buttons displayed within the DateFilter item. Each button has a DateTime range assigned to it. You can click the button to apply that range as a Date filter.

To add a quick filter, create the DateTimePeriod objects and add them to the DateFilterDashboardItem.DateTimePeriods collection.

Arrange Quick Filters

Quick filters in the DateFilter item can be arranged horizontally or vertically. The default mode is auto height, in which quick filters are displayed horizontally and the dashboard item shrinks automatically to fit the items and save space.

Use the DateFilterDashboardItem.ArrangementMode property to specify the arrangement mode.

Example

The following code snippet creates a DateFilter dashboard item in code:

C#

using DevExpress.DashboardCommon;
using DevExpress.DashboardWin.Localization;
using DevExpress.DataAccess.Excel;
using DevExpress.XtraEditors;
using System;

namespace DateFilterDashboardItemSample
{
    public partial class Form1 : XtraForm
    {
        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {
            DashboardExcelDataSource excelDataSource = CreateExcelDataSource();
            Dashboard dBoard = new Dashboard();
            dBoard.DataSources.Add(excelDataSource);

            dBoard.BeginUpdate();
            // Create dashboard items.
            ChartDashboardItem chart = CreateChart(excelDataSource);
            dBoard.Items.Add(chart);
            DateFilterDashboardItem dateFilterItem = CreateDateFilterItem(excelDataSource);
            dBoard.Items.Add(dateFilterItem);
            DashboardItemGroup group = CreateGroup();
            dBoard.Groups.Add(group);
            group.AddRange(dateFilterItem, chart);
            // Create the layout tree.
            DashboardLayoutItem dateFilterLayoutItem = new DashboardLayoutItem(dateFilterItem, 30);
            DashboardLayoutItem chartLayoutItem = new DashboardLayoutItem(chart, 70);
            DashboardLayoutGroup groupLayoutItem = new DashboardLayoutGroup(group, 100);
            groupLayoutItem.ChildNodes.AddRange(dateFilterLayoutItem, chartLayoutItem);
            DashboardLayoutGroup rootGroup = new DashboardLayoutGroup(null, 100);
            rootGroup.ChildNodes.Add(groupLayoutItem);
            rootGroup.Orientation = DashboardLayoutGroupOrientation.Vertical;
            dBoard.LayoutRoot = rootGroup;
            dBoard.EndUpdate();

            dashboardViewer1.Dashboard = dBoard;
        }

        private DashboardItemGroup CreateGroup()
        {
            DashboardItemGroup group = new DashboardItemGroup();
            group.Name = "Sales by Date";
            return group;
        }

        private DateFilterDashboardItem CreateDateFilterItem(DashboardExcelDataSource excelDataSource)
        {
            DateFilterDashboardItem dateFilter = new DateFilterDashboardItem();
            dateFilter.Name = string.Empty;
            dateFilter.ShowCaption = false;
            dateFilter.DataSource = excelDataSource;
            dateFilter.Dimension = new Dimension("orderDateId", "OrderDate", DateTimeGroupInterval.DayMonthYear);
            dateFilter.Dimension.DateTimeFormat.DateTimeFormat = DateTimeFormat.Short;
            dateFilter.ArrangementMode = DateFilterArrangementMode.Vertical;
            dateFilter.FilterType = DateFilterType.Between;
            dateFilter.DatePickerLocation = DatePickerLocation.Far;
            dateFilter.DateTimePeriods.AddRange(
                DateTimePeriod.CreateLastYear(),
                DateTimePeriod.CreateNextDays("Next 7 Days", 7),
                new DateTimePeriod
                {
                    Name = DashboardWinLocalizer.GetString(DashboardWinStringId.PeriodMonthToDate),
                    Start = new FlowDateTimePeriodLimit
                    {
                        Interval = DateTimeInterval.Month,
                        Offset = 0
                    },
                    End = new FlowDateTimePeriodLimit
                    {
                        Interval = DateTimeInterval.Day,
                        Offset = 1
                    }
                },
                new DateTimePeriod
                {
                    Name = "Jul-18-2018 - Jan-18-2019",
                    Start = new FixedDateTimePeriodLimit
                    {
                        Date = new DateTime(2018, 7, 18)
                    },
                    End = new FixedDateTimePeriodLimit
                    {
                        Date = new DateTime(2019, 1, 18)
                    }
                }
            );
            return dateFilter;
        }

        private ChartDashboardItem CreateChart(DashboardExcelDataSource excelDataSource)
        {
            ChartDashboardItem chart = new ChartDashboardItem();
            chart.Name = string.Empty;
            chart.ShowCaption = false;
            chart.DataSource = excelDataSource;
            chart.Arguments.Add(new Dimension("OrderDate", DateTimeGroupInterval.DayMonthYear));
            chart.Panes.Add(new ChartPane());
            SimpleSeries salesAmountSeries = new SimpleSeries(SimpleSeriesType.Line);
            salesAmountSeries.Value = new Measure("Extended Price");
            chart.Panes[0].Series.Add(salesAmountSeries);
            return chart;
        }

        private DashboardExcelDataSource CreateExcelDataSource()
        {
            DashboardExcelDataSource excelDataSource = new DashboardExcelDataSource();
            excelDataSource.FileName = "SalesPerson.xlsx";
            ExcelWorksheetSettings worksheetSettings = new ExcelWorksheetSettings("Data");
            excelDataSource.SourceOptions = new ExcelSourceOptions(worksheetSettings);
            excelDataSource.Fill();
            return excelDataSource;
        }
    }
}

VB.NET

Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin.Localization
Imports DevExpress.DataAccess.Excel
Imports DevExpress.XtraEditors
Imports System

Namespace DateFilterDashboardItemSample
    Partial Public Class Form1
        Inherits XtraForm

        Public Sub New()
            InitializeComponent()
        End Sub

        Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) Handles Me.Load
            Dim excelDataSource As DashboardExcelDataSource = CreateExcelDataSource()
            Dim dBoard As New Dashboard()
            dBoard.DataSources.Add(excelDataSource)

            dBoard.BeginUpdate()
            ' Create dashboard items.
            Dim chart As ChartDashboardItem = CreateChart(excelDataSource)
            dBoard.Items.Add(chart)
            Dim dateFilterItem As DateFilterDashboardItem = CreateDateFilterItem(excelDataSource)
            dBoard.Items.Add(dateFilterItem)
            Dim group As DashboardItemGroup = CreateGroup()
            dBoard.Groups.Add(group)
            group.AddRange(dateFilterItem, chart)
            ' Create the layout tree.
            Dim dateFilterLayoutItem As New DashboardLayoutItem(dateFilterItem, 30)
            Dim chartLayoutItem As New DashboardLayoutItem(chart, 70)
            Dim groupLayoutItem As New DashboardLayoutGroup(group, 100)
            groupLayoutItem.ChildNodes.AddRange(dateFilterLayoutItem, chartLayoutItem)
            Dim rootGroup As New DashboardLayoutGroup()
            rootGroup.DashboardItem = Nothing
            rootGroup.Weight = 100
            rootGroup.ChildNodes.Add(groupLayoutItem)
            rootGroup.Orientation = DashboardLayoutGroupOrientation.Vertical
            dBoard.LayoutRoot = rootGroup
            dBoard.EndUpdate()

            dashboardViewer1.Dashboard = dBoard
        End Sub

        Private Function CreateGroup() As DashboardItemGroup
            Dim group As New DashboardItemGroup()
            group.Name = "Sales by Date"
            Return group
        End Function

        Private Function CreateDateFilterItem(ByVal excelDataSource As DashboardExcelDataSource) As DateFilterDashboardItem
            Dim dateFilter As New DateFilterDashboardItem()
            dateFilter.Name = String.Empty
            dateFilter.ShowCaption = False
            dateFilter.DataSource = excelDataSource
            dateFilter.Dimension = New Dimension("orderDateId", "OrderDate", DateTimeGroupInterval.DayMonthYear)
            dateFilter.Dimension.DateTimeFormat.DateTimeFormat = DateTimeFormat.Short
            dateFilter.ArrangementMode = DateFilterArrangementMode.Vertical
            dateFilter.FilterType = DateFilterType.Between
            dateFilter.DatePickerLocation = DatePickerLocation.Far
            dateFilter.DateTimePeriods.AddRange(DateTimePeriod.CreateLastYear(), DateTimePeriod.CreateNextDays("Next 7 Days", 7), New DateTimePeriod With {
                .Name = DashboardWinLocalizer.GetString(DashboardWinStringId.PeriodMonthToDate), .Start = New FlowDateTimePeriodLimit With {.Interval = DateTimeInterval.Month, .Offset = 0},
                .End = New FlowDateTimePeriodLimit With {.Interval = DateTimeInterval.Day, .Offset = 1}
            },
            New DateTimePeriod With {
                .Name = "Jul-18-2018 - Jan-18-2019", .Start = New FixedDateTimePeriodLimit With {.Date = New Date(2018, 7, 18)},
                .End = New FixedDateTimePeriodLimit With {.Date = New Date(2019, 1, 18)}
            })
            Return dateFilter
        End Function

        Private Function CreateChart(ByVal excelDataSource As DashboardExcelDataSource) As ChartDashboardItem
            Dim chart As New ChartDashboardItem()
            chart.Name = String.Empty
            chart.ShowCaption = False
            chart.DataSource = excelDataSource
            chart.Arguments.Add(New Dimension("OrderDate", DateTimeGroupInterval.DayMonthYear))
            chart.Panes.Add(New ChartPane())
            Dim salesAmountSeries As New SimpleSeries(SimpleSeriesType.Line)
            salesAmountSeries.Value = New Measure("Extended Price")
            chart.Panes(0).Series.Add(salesAmountSeries)
            Return chart
        End Function

        Private Function CreateExcelDataSource() As DashboardExcelDataSource
            Dim excelDataSource As New DashboardExcelDataSource()
            excelDataSource.FileName = "SalesPerson.xlsx"
            Dim worksheetSettings As New ExcelWorksheetSettings("Data")
            excelDataSource.SourceOptions = New ExcelSourceOptions(worksheetSettings)
            excelDataSource.Fill()
            Return excelDataSource
        End Function
    End Class
End Namespace

Implements

ICustomPropertyProvider

Inheritance

Object

DashboardItem

DataDashboardItem

DateFilterDashboardItem